home *** CD-ROM | disk | FTP | other *** search
/ Australian Personal Computer 2002 November / CD 1 / APC0211D1.ISO / workshop / prog / files / ActivePerl-5.6.1.633-MSWin32.msi / _a950e35b5cccaa856181f57ccb9964f9 < prev    next >
Encoding:
Text File  |  2002-06-17  |  82.6 KB  |  3,004 lines
  1. #######################################################################
  2. #
  3. # Win32::Internet - Perl Module for Internet Extensions
  4. # ^^^^^^^^^^^^^^^
  5. # This module creates an object oriented interface to the Win32
  6. # Internet Functions (WININET.DLL).
  7. #
  8. # Version: 0.08  (14 Feb 1997)
  9. # Version: 0.081 (25 Sep 1999)
  10. # Version: 0.082 (04 Sep 2001)
  11. #
  12. #######################################################################
  13.  
  14. # changes:
  15. # - fixed 2 bugs in Option(s) related subs
  16. # - works with build 30x also
  17.  
  18. package Win32::Internet;
  19.  
  20. require Exporter;       # to export the constants to the main:: space
  21. require DynaLoader;     # to dynuhlode the module.
  22.  
  23. # use Win32::WinError;    # for windows constants.
  24.  
  25. @ISA= qw( Exporter DynaLoader );
  26. @EXPORT = qw(
  27.     HTTP_ADDREQ_FLAG_ADD
  28.     HTTP_ADDREQ_FLAG_REPLACE
  29.     HTTP_QUERY_ALLOW
  30.     HTTP_QUERY_CONTENT_DESCRIPTION
  31.     HTTP_QUERY_CONTENT_ID
  32.     HTTP_QUERY_CONTENT_LENGTH
  33.     HTTP_QUERY_CONTENT_TRANSFER_ENCODING
  34.     HTTP_QUERY_CONTENT_TYPE
  35.     HTTP_QUERY_COST
  36.     HTTP_QUERY_CUSTOM
  37.     HTTP_QUERY_DATE
  38.     HTTP_QUERY_DERIVED_FROM
  39.     HTTP_QUERY_EXPIRES
  40.     HTTP_QUERY_FLAG_REQUEST_HEADERS
  41.     HTTP_QUERY_FLAG_SYSTEMTIME
  42.     HTTP_QUERY_LANGUAGE
  43.     HTTP_QUERY_LAST_MODIFIED
  44.     HTTP_QUERY_MESSAGE_ID
  45.     HTTP_QUERY_MIME_VERSION
  46.     HTTP_QUERY_PRAGMA
  47.     HTTP_QUERY_PUBLIC
  48.     HTTP_QUERY_RAW_HEADERS
  49.     HTTP_QUERY_RAW_HEADERS_CRLF
  50.     HTTP_QUERY_REQUEST_METHOD
  51.     HTTP_QUERY_SERVER
  52.     HTTP_QUERY_STATUS_CODE
  53.     HTTP_QUERY_STATUS_TEXT
  54.     HTTP_QUERY_URI
  55.     HTTP_QUERY_USER_AGENT
  56.     HTTP_QUERY_VERSION
  57.     HTTP_QUERY_WWW_LINK
  58.     ICU_BROWSER_MODE
  59.     ICU_DECODE
  60.     ICU_ENCODE_SPACES_ONLY
  61.     ICU_ESCAPE
  62.     ICU_NO_ENCODE
  63.     ICU_NO_META
  64.     ICU_USERNAME
  65.     INTERNET_FLAG_PASSIVE
  66.     INTERNET_FLAG_ASYNC
  67.     INTERNET_HYPERLINK
  68.     INTERNET_FLAG_KEEP_CONNECTION
  69.     INTERNET_FLAG_MAKE_PERSISTENT
  70.     INTERNET_FLAG_NO_AUTH
  71.     INTERNET_FLAG_NO_AUTO_REDIRECT
  72.     INTERNET_FLAG_NO_CACHE_WRITE
  73.     INTERNET_FLAG_NO_COOKIES
  74.     INTERNET_FLAG_READ_PREFETCH
  75.     INTERNET_FLAG_RELOAD
  76.     INTERNET_FLAG_RESYNCHRONIZE
  77.     INTERNET_FLAG_TRANSFER_ASCII
  78.     INTERNET_FLAG_TRANSFER_BINARY
  79.     INTERNET_INVALID_PORT_NUMBER
  80.     INTERNET_INVALID_STATUS_CALLBACK
  81.     INTERNET_OPEN_TYPE_DIRECT
  82.     INTERNET_OPEN_TYPE_PROXY
  83.     INTERNET_OPEN_TYPE_PROXY_PRECONFIG
  84.     INTERNET_OPTION_CONNECT_BACKOFF
  85.     INTERNET_OPTION_CONNECT_RETRIES
  86.     INTERNET_OPTION_CONNECT_TIMEOUT
  87.     INTERNET_OPTION_CONTROL_SEND_TIMEOUT
  88.     INTERNET_OPTION_CONTROL_RECEIVE_TIMEOUT
  89.     INTERNET_OPTION_DATA_SEND_TIMEOUT
  90.     INTERNET_OPTION_DATA_RECEIVE_TIMEOUT
  91.     INTERNET_OPTION_HANDLE_SIZE
  92.     INTERNET_OPTION_LISTEN_TIMEOUT
  93.     INTERNET_OPTION_PASSWORD
  94.     INTERNET_OPTION_READ_BUFFER_SIZE
  95.     INTERNET_OPTION_USER_AGENT
  96.     INTERNET_OPTION_USERNAME
  97.     INTERNET_OPTION_VERSION
  98.     INTERNET_OPTION_WRITE_BUFFER_SIZE
  99.     INTERNET_SERVICE_FTP
  100.     INTERNET_SERVICE_GOPHER
  101.     INTERNET_SERVICE_HTTP
  102.     INTERNET_STATUS_CLOSING_CONNECTION
  103.     INTERNET_STATUS_CONNECTED_TO_SERVER    
  104.     INTERNET_STATUS_CONNECTING_TO_SERVER
  105.     INTERNET_STATUS_CONNECTION_CLOSED
  106.     INTERNET_STATUS_HANDLE_CLOSING
  107.     INTERNET_STATUS_HANDLE_CREATED
  108.     INTERNET_STATUS_NAME_RESOLVED
  109.     INTERNET_STATUS_RECEIVING_RESPONSE
  110.     INTERNET_STATUS_REDIRECT    
  111.     INTERNET_STATUS_REQUEST_COMPLETE    
  112.     INTERNET_STATUS_REQUEST_SENT    
  113.     INTERNET_STATUS_RESOLVING_NAME    
  114.     INTERNET_STATUS_RESPONSE_RECEIVED
  115.     INTERNET_STATUS_SENDING_REQUEST    
  116. );
  117.  
  118.  
  119. #######################################################################
  120. # This AUTOLOAD is used to 'autoload' constants from the constant()
  121. # XS function.  If a constant is not found then control is passed
  122. # to the AUTOLOAD in AutoLoader.
  123. #
  124.  
  125. sub AUTOLOAD {
  126.     my($constname);
  127.     ($constname = $AUTOLOAD) =~ s/.*:://;
  128.     #reset $! to zero to reset any current errors.
  129.     local $! = 0;
  130.     my $val = constant($constname, @_ ? $_[0] : 0);
  131.     if ($! != 0) {
  132.  
  133.         # [dada] This results in an ugly Autoloader error
  134.         #if ($! =~ /Invalid/) {
  135.         #  $AutoLoader::AUTOLOAD = $AUTOLOAD;
  136.         #  goto &AutoLoader::AUTOLOAD;
  137.         #} else {
  138.       
  139.         # [dada] ... I prefer this one :)
  140.   
  141.             ($pack,$file,$line) = caller; undef $pack;
  142.             die "Win32::Internet::$constname is not defined, used at $file line $line.";
  143.   
  144.         #}
  145.     }
  146.     eval "sub $AUTOLOAD { $val }";
  147.     goto &$AUTOLOAD;
  148. }
  149.  
  150.  
  151. #######################################################################
  152. # STATIC OBJECT PROPERTIES
  153. #
  154. $VERSION = "0.082";
  155.  
  156. %callback_code = ();
  157. %callback_info = ();
  158.  
  159.  
  160. #######################################################################
  161. # PUBLIC METHODS
  162. #
  163.  
  164. #======== ### CLASS CONSTRUCTOR
  165. sub new {
  166. #========
  167.     my($class, $useragent, $opentype, $proxy, $proxybypass, $flags) = @_;
  168.     my $self = {};  
  169.  
  170.     if(ref($useragent) and ref($useragent) eq "HASH") {
  171.         $opentype       = $useragent->{'opentype'};
  172.         $proxy          = $useragent->{'proxy'};
  173.         $proxybypass    = $useragent->{'proxybypass'};
  174.         $flags          = $useragent->{'flags'};
  175.         my $myuseragent = $useragent->{'useragent'};
  176.         undef $useragent;
  177.         $useragent      = $myuseragent;
  178.     }
  179.  
  180.     $useragent = "Perl-Win32::Internet/".$VERSION       unless defined($useragent);
  181.     $opentype = constant("INTERNET_OPEN_TYPE_DIRECT",0) unless defined($opentype);
  182.     $proxy = ""                                         unless defined($proxy);
  183.     $proxybypass = ""                                   unless defined($proxybypass);
  184.     $flags = 0                                          unless defined($flags);
  185.  
  186.  
  187.     my $handle = InternetOpen($useragent, $opentype, $proxy, $proxybypass, $flags);
  188.     if ($handle) {
  189.         $self->{'connections'} = 0;
  190.         $self->{'pasv'}        = 0;
  191.         $self->{'handle'}      = $handle; 
  192.         $self->{'useragent'}   = $useragent;
  193.         $self->{'proxy'}       = $proxy;
  194.         $self->{'proxybypass'} = $proxybypass;
  195.         $self->{'flags'}       = $flags;
  196.         $self->{'Type'}        = "Internet";
  197.     
  198.         # [dada] I think it's better to call SetStatusCallback explicitly...
  199.         #if($flags & constant("INTERNET_FLAG_ASYNC",0)) {
  200.         #  my $callbackresult=InternetSetStatusCallback($handle);
  201.         #  if($callbackresult==&constant("INTERNET_INVALID_STATUS_CALLBACK",0)) {
  202.         #    $self->{'Error'} = -2;
  203.         #  }
  204.         #}
  205.  
  206.         bless $self;
  207.     } else {
  208.         $self->{'handle'} = undef;
  209.         bless $self;
  210.     }
  211.     $self;
  212. }  
  213.  
  214.  
  215. #============
  216. sub OpenURL {
  217. #============
  218.     my($self,$new,$URL) = @_;
  219.     return undef unless ref($self);
  220.  
  221.     my $newhandle=InternetOpenUrl($self->{'handle'},$URL,"",0,0,0);
  222.     if(!$newhandle) {
  223.         $self->{'Error'} = "Cannot open URL.";
  224.         return undef;
  225.     } else {
  226.         $self->{'connections'}++;
  227.         $_[1] = _new($newhandle);
  228.         $_[1]->{'Type'} = "URL";
  229.         $_[1]->{'URL'}  = $URL;
  230.         return $newhandle;
  231.     }
  232. }
  233.  
  234.  
  235. #================
  236. sub TimeConvert {
  237. #================
  238.     my($self, $sec, $min, $hour, $day, $mon, $year, $wday, $rfc) = @_;
  239.     return undef unless ref($self);
  240.  
  241.     if(!defined($rfc)) {
  242.         return InternetTimeToSystemTime($sec);
  243.     } else {
  244.         return InternetTimeFromSystemTime($sec, $min, $hour, 
  245.                                           $day, $mon, $year, 
  246.                                           $wday, $rfc);
  247.     }
  248. }
  249.  
  250.  
  251. #=======================
  252. sub QueryDataAvailable {
  253. #=======================
  254.     my($self) = @_;
  255.     return undef unless ref($self);
  256.   
  257.     return InternetQueryDataAvailable($self->{'handle'});
  258. }
  259.  
  260.  
  261. #=============
  262. sub ReadFile {
  263. #=============
  264.     my($self, $buffersize) = @_;
  265.     return undef unless ref($self);
  266.  
  267.     my $howmuch = InternetQueryDataAvailable($self->{'handle'});
  268.     $buffersize = $howmuch unless defined($buffersize);
  269.     return InternetReadFile($self->{'handle'}, ($howmuch<$buffersize) ? $howmuch 
  270.                                                                       : $buffersize);
  271. }
  272.  
  273.  
  274. #===================
  275. sub ReadEntireFile {
  276. #===================
  277.     my($handle) = @_;
  278.     my $content    = "";
  279.     my $buffersize = 16000;
  280.     my $howmuch    = 0;
  281.     my $buffer     = "";
  282.  
  283.     $handle = $handle->{'handle'} if defined($handle) and ref($handle);
  284.  
  285.     $howmuch = InternetQueryDataAvailable($handle);
  286.     # print "\nReadEntireFile: $howmuch bytes to read...\n";
  287.   
  288.     while($howmuch>0) {
  289.         $buffer = InternetReadFile($handle, ($howmuch<$buffersize) ? $howmuch 
  290.                                                                    : $buffersize);
  291.         # print "\nReadEntireFile: ", length($buffer), " bytes read...\n";
  292.     
  293.         if(!defined($buffer)) {
  294.             return undef;
  295.         } else {
  296.             $content .= $buffer;
  297.         }
  298.         $howmuch = InternetQueryDataAvailable($handle);
  299.         # print "\nReadEntireFile: still $howmuch bytes to read...\n";
  300.     
  301.     }
  302.     return $content;
  303. }
  304.  
  305.  
  306. #=============
  307. sub FetchURL {
  308. #=============
  309.     # (OpenURL+Read+Close)...
  310.     my($self, $URL) = @_;
  311.     return undef unless ref($self);
  312.  
  313.     my $newhandle = InternetOpenUrl($self->{'handle'}, $URL, "", 0, 0, 0);
  314.     if(!$newhandle) {
  315.         $self->{'Error'} = "Cannot open URL.";
  316.         return undef;
  317.     } else {
  318.         my $content = ReadEntireFile($newhandle);
  319.         InternetCloseHandle($newhandle);
  320.         return $content;
  321.     }
  322. }
  323.  
  324.  
  325. #================
  326. sub Connections {
  327. #================
  328.     my($self) = @_;
  329.     return undef unless ref($self);
  330.  
  331.     return $self->{'connections'} if $self->{'Type'} eq "Internet";
  332.     return undef;
  333. }
  334.  
  335.  
  336. #================
  337. sub GetResponse {
  338. #================
  339.     my($num, $text) = InternetGetLastResponseInfo();
  340.     return $text;
  341. }
  342.  
  343. #===========
  344. sub Option {
  345. #===========
  346.     my($self, $option, $value) = @_;
  347.     return undef unless ref($self);
  348.  
  349.     my $retval = 0;
  350.  
  351.     $option = constant("INTERNET_OPTION_USER_AGENT", 0) unless defined($option);
  352.   
  353.     if(!defined($value)) {
  354.         $retval = InternetQueryOption($self->{'handle'}, $option);
  355.     } else {
  356.         $retval = InternetSetOption($self->{'handle'}, $option, $value);
  357.     }
  358.     return $retval;
  359. }
  360.  
  361.  
  362. #==============
  363. sub UserAgent {
  364. #==============
  365.     my($self, $value) = @_;
  366.     return undef unless ref($self);
  367.  
  368.     return Option($self, constant("INTERNET_OPTION_USER_AGENT", 0), $value);
  369. }
  370.  
  371.  
  372. #=============
  373. sub Username {
  374. #=============
  375.     my($self, $value) = @_;
  376.     return undef unless ref($self);
  377.   
  378.     if($self->{'Type'} ne "HTTP" and $self->{'Type'} ne "FTP") {
  379.         $self->{'Error'} = "Username() only on FTP or HTTP sessions.";
  380.         return undef;
  381.     }
  382.  
  383.     return Option($self, constant("INTERNET_OPTION_USERNAME", 0), $value);
  384. }
  385.  
  386.  
  387. #=============
  388. sub Password {
  389. #=============
  390.     my($self, $value)=@_;
  391.     return undef unless ref($self);
  392.  
  393.     if($self->{'Type'} ne "HTTP" and $self->{'Type'} ne "FTP") {
  394.         $self->{'Error'} = "Password() only on FTP or HTTP sessions.";
  395.         return undef;
  396.     }
  397.  
  398.     return Option($self, constant("INTERNET_OPTION_PASSWORD", 0), $value);
  399. }
  400.  
  401.  
  402. #===================
  403. sub ConnectTimeout {
  404. #===================
  405.     my($self, $value) = @_;
  406.     return undef unless ref($self);
  407.  
  408.     return Option($self, constant("INTERNET_OPTION_CONNECT_TIMEOUT", 0), $value);
  409. }
  410.  
  411.  
  412. #===================
  413. sub ConnectRetries {
  414. #===================
  415.     my($self, $value) = @_;
  416.     return undef unless ref($self);
  417.  
  418.     return Option($self, constant("INTERNET_OPTION_CONNECT_RETRIES", 0), $value);
  419. }
  420.  
  421.  
  422. #===================
  423. sub ConnectBackoff {
  424. #===================
  425.     my($self,$value)=@_;
  426.     return undef unless ref($self);
  427.  
  428.     return Option($self, constant("INTERNET_OPTION_CONNECT_BACKOFF", 0), $value);
  429. }
  430.  
  431.  
  432. #====================
  433. sub DataSendTimeout {
  434. #====================
  435.     my($self,$value) = @_;
  436.     return undef unless ref($self);
  437.  
  438.     return Option($self, constant("INTERNET_OPTION_DATA_SEND_TIMEOUT", 0), $value);
  439. }
  440.  
  441.  
  442. #=======================
  443. sub DataReceiveTimeout {
  444. #=======================
  445.     my($self, $value) = @_;
  446.     return undef unless ref($self);
  447.  
  448.     return Option($self, constant("INTERNET_OPTION_DATA_RECEIVE_TIMEOUT", 0), $value);
  449. }
  450.  
  451.  
  452. #==========================
  453. sub ControlReceiveTimeout {
  454. #==========================
  455.     my($self, $value) = @_;
  456.     return undef unless ref($self);
  457.  
  458.     return Option($self, constant("INTERNET_OPTION_CONTROL_RECEIVE_TIMEOUT", 0), $value);
  459. }
  460.  
  461.  
  462. #=======================
  463. sub ControlSendTimeout {
  464. #=======================
  465.     my($self, $value) = @_;
  466.     return undef unless ref($self);
  467.  
  468.     return Option($self, constant("INTERNET_OPTION_CONTROL_SEND_TIMEOUT", 0), $value);
  469. }
  470.  
  471.  
  472. #================
  473. sub QueryOption {
  474. #================
  475.     my($self, $option) = @_;
  476.     return undef unless ref($self);
  477.  
  478.     return InternetQueryOption($self->{'handle'}, $option);
  479. }
  480.  
  481.  
  482. #==============
  483. sub SetOption {
  484. #==============
  485.     my($self, $option, $value) = @_;
  486.     return undef unless ref($self);
  487.  
  488.     return InternetSetOption($self->{'handle'}, $option, $value);
  489. }
  490.  
  491.  
  492. #=============
  493. sub CrackURL {
  494. #=============
  495.     my($self, $URL, $flags) = @_;
  496.     return undef unless ref($self);
  497.  
  498.     $flags = constant("ICU_ESCAPE", 0) unless defined($flags);
  499.   
  500.     my @newurl = InternetCrackUrl($URL, $flags);
  501.   
  502.     if(!defined($newurl[0])) {
  503.         $self->{'Error'} = "Cannot crack URL.";
  504.         return undef;
  505.     } else {
  506.         return @newurl;
  507.     }
  508. }
  509.  
  510.  
  511. #==============
  512. sub CreateURL {
  513. #==============
  514.     my($self, $scheme, $hostname, $port, 
  515.        $username, $password, 
  516.        $path, $extrainfo, $flags) = @_;
  517.     return undef unless ref($self);
  518.  
  519.     if(ref($scheme) and ref($scheme) eq "HASH") {
  520.         $flags       = $hostname;
  521.         $hostname    = $scheme->{'hostname'};
  522.         $port        = $scheme->{'port'};
  523.         $username    = $scheme->{'username'};
  524.         $password    = $scheme->{'password'};
  525.         $path        = $scheme->{'path'};
  526.         $extrainfo   = $scheme->{'extrainfo'};
  527.         my $myscheme = $scheme->{'scheme'};
  528.         undef $scheme;
  529.         $scheme      = $myscheme;
  530.     }
  531.  
  532.     $hostname  = ""                    unless defined($hostname);
  533.     $port      = 0                     unless defined($port);
  534.     $username  = ""                    unless defined($username);
  535.     $password  = ""                    unless defined($password);
  536.     $path      = ""                    unless defined($path);
  537.     $extrainfo = ""                    unless defined($extrainfo);
  538.     $flags = constant("ICU_ESCAPE", 0) unless defined($flags);
  539.   
  540.     my $newurl = InternetCreateUrl($scheme, $hostname, $port,
  541.                                    $username, $password,
  542.                                    $path, $extrainfo, $flags);
  543.     if(!defined($newurl)) {
  544.         $self->{'Error'} = "Cannot create URL.";
  545.         return undef;
  546.     } else {
  547.         return $newurl;
  548.     }
  549. }
  550.  
  551.  
  552. #====================
  553. sub CanonicalizeURL {
  554. #====================
  555.     my($self, $URL, $flags) = @_;
  556.     return undef unless ref($self);
  557.   
  558.     my $newurl = InternetCanonicalizeUrl($URL, $flags);
  559.     if(!defined($newurl)) {
  560.         $self->{'Error'} = "Cannot canonicalize URL.";
  561.         return undef;
  562.     } else {
  563.         return $newurl;
  564.     }
  565. }
  566.  
  567.  
  568. #===============
  569. sub CombineURL {
  570. #===============
  571.     my($self, $baseURL, $relativeURL, $flags) = @_;
  572.     return undef unless ref($self);
  573.   
  574.     my $newurl = InternetCombineUrl($baseURL, $relativeURL, $flags);
  575.     if(!defined($newurl)) {
  576.         $self->{'Error'} = "Cannot combine URL(s).";
  577.         return undef;
  578.     } else {
  579.         return $newurl;
  580.     }
  581. }
  582.  
  583.  
  584. #======================
  585. sub SetStatusCallback {
  586. #======================
  587.     my($self) = @_;
  588.     return undef unless ref($self);
  589.   
  590.     my $callback = InternetSetStatusCallback($self->{'handle'});
  591.     print "callback=$callback, constant=",constant("INTERNET_INVALID_STATUS_CALLBACK", 0), "\n";
  592.     if($callback == constant("INTERNET_INVALID_STATUS_CALLBACK", 0)) {
  593.         return undef;
  594.     } else {
  595.         return $callback;
  596.     }
  597. }
  598.  
  599.  
  600. #======================
  601. sub GetStatusCallback {
  602. #======================
  603.     my($self, $context) = @_;
  604.     $context = $self if not defined $context;
  605.     return($callback_code{$context}, $callback_info{$context});
  606. }
  607.  
  608.  
  609. #==========
  610. sub Error {
  611. #==========
  612.     my($self) = @_;
  613.     return undef unless ref($self);
  614.   
  615.     my $errtext = "";
  616.     my $tmp     = "";
  617.     my $errnum  = Win32::GetLastError();
  618.  
  619.     if($errnum < 12000) {
  620.         $errtext =  Win32::FormatMessage($errnum);
  621.         $errtext =~ s/[\r\n]//g;
  622.     } elsif($errnum == 12003) {
  623.         ($tmp, $errtext) = InternetGetLastResponseInfo();
  624.         chomp $errtext;
  625.         1 while($errtext =~ s/(.*)\n//); # the last line should be significative... 
  626.                                          # otherwise call GetResponse() to get it whole
  627.     } elsif($errnum >= 12000) {
  628.         $errtext = FormatMessage($errnum);
  629.         $errtext =~ s/[\r\n]//g;        
  630.     } else {
  631.         $errtext="Error";
  632.     }
  633.     if($errnum == 0 and defined($self->{'Error'})) { 
  634.         if($self->{'Error'} == -2) {
  635.             $errnum  = -2;
  636.             $errtext = "Asynchronous operations not available.";
  637.         } else {
  638.             $errnum  = -1;
  639.             $errtext = $self->{'Error'};
  640.         }
  641.     }
  642.     return (wantarray)? ($errnum, $errtext) : "\[".$errnum."\] ".$errtext;
  643. }
  644.  
  645.  
  646. #============
  647. sub Version {
  648. #============
  649.     my $dll =  InternetDllVersion();
  650.        $dll =~ s/\0//g;
  651.     return (wantarray)? ($Win32::Internet::VERSION,    $dll) 
  652.                       :  $Win32::Internet::VERSION."/".$dll;
  653. }
  654.  
  655.  
  656. #==========
  657. sub Close {
  658. #==========
  659.     my($self, $handle) = @_;
  660.     if(!defined($handle)) {
  661.         return undef unless ref($self);
  662.         $handle = $self->{'handle'};
  663.     }
  664.     InternetCloseHandle($handle);
  665. }
  666.  
  667.  
  668.  
  669. #######################################################################
  670. # FTP CLASS METHODS
  671. #
  672.  
  673. #======== ### FTP CONSTRUCTOR
  674. sub FTP {
  675. #========
  676.     my($self, $new, $server, $username, $password, $port, $pasv, $context) = @_;    
  677.     return undef unless ref($self);
  678.  
  679.     if(ref($server) and ref($server) eq "HASH") {
  680.         $port        = $server->{'port'};
  681.         $username    = $server->{'username'};
  682.         $password    = $password->{'host'};
  683.         my $myserver = $server->{'server'};
  684.         $pasv        = $server->{'pasv'};
  685.         $context     = $server->{'context'};
  686.         undef $server;
  687.         $server      = $myserver;
  688.     }
  689.  
  690.     $server   = ""          unless defined($server);
  691.     $username = "anonymous" unless defined($username);
  692.     $password = ""          unless defined($password);
  693.     $port     = 21          unless defined($port);
  694.     $context  = 0           unless defined($context);
  695.  
  696.     $pasv = $self->{'pasv'} unless defined $pasv;
  697.     $pasv = $pasv ? constant("INTERNET_FLAG_PASSIVE",0) : 0;
  698.  
  699.     my $newhandle = InternetConnect($self->{'handle'}, $server, $port,
  700.                                     $username, $password,
  701.                                     constant("INTERNET_SERVICE_FTP", 0),
  702.                                     $pasv, $context);
  703.     if($newhandle) {
  704.         $self->{'connections'}++;
  705.         $_[1] = _new($newhandle);
  706.         $_[1]->{'Type'}     = "FTP";
  707.         $_[1]->{'Mode'}     = "bin";
  708.         $_[1]->{'pasv'}     = $pasv;
  709.         $_[1]->{'username'} = $username;
  710.         $_[1]->{'password'} = $password;
  711.         $_[1]->{'server'}   = $server;
  712.         return $newhandle;
  713.     } else {
  714.         return undef;
  715.     }
  716. }
  717.  
  718. #========
  719. sub Pwd {
  720. #========
  721.     my($self) = @_;
  722.     return undef unless ref($self);
  723.  
  724.     if($self->{'Type'} ne "FTP" or !defined($self->{'handle'})) {
  725.         $self->{'Error'} = "Pwd() only on FTP sessions.";
  726.         return undef;
  727.     }
  728.   
  729.     return FtpGetCurrentDirectory($self->{'handle'});
  730. }
  731.  
  732.  
  733. #=======
  734. sub Cd {
  735. #=======
  736.     my($self, $path) = @_;
  737.     return undef unless ref($self);
  738.  
  739.     if($self->{'Type'} ne "FTP" || !defined($self->{'handle'})) {
  740.         $self->{'Error'} = "Cd() only on FTP sessions.";
  741.         return undef;
  742.     }
  743.   
  744.     my $retval = FtpSetCurrentDirectory($self->{'handle'}, $path);
  745.     if(!defined($retval)) {
  746.         return undef;
  747.     } else {
  748.         return $path;
  749.     }
  750. }
  751. #====================
  752. sub Cwd   { Cd(@_); }
  753. sub Chdir { Cd(@_); }
  754. #====================
  755.  
  756.  
  757. #==========
  758. sub Mkdir {
  759. #==========
  760.     my($self, $path) = @_;
  761.     return undef unless ref($self);
  762.  
  763.     if($self->{'Type'} ne "FTP" or !defined($self->{'handle'})) {
  764.         $self->{'Error'} = "Mkdir() only on FTP sessions.";
  765.         return undef;
  766.     }
  767.   
  768.     my $retval = FtpCreateDirectory($self->{'handle'}, $path);
  769.     $self->{'Error'} = "Can't create directory." unless defined($retval);
  770.     return $retval;
  771. }
  772. #====================
  773. sub Md { Mkdir(@_); }
  774. #====================
  775.  
  776.  
  777. #=========
  778. sub Mode {
  779. #=========
  780.     my($self, $value) = @_;
  781.     return undef unless ref($self);
  782.  
  783.     if($self->{'Type'} ne "FTP" or !defined($self->{'handle'})) {
  784.         $self->{'Error'} = "Mode() only on FTP sessions.";
  785.         return undef;
  786.     }
  787.   
  788.     if(!defined($value)) {
  789.         return $self->{'Mode'};
  790.     } else {
  791.         my $modesub = ($value =~ /^a/i) ? "Ascii" : "Binary";
  792.         $self->$modesub($_[0]);
  793.     }
  794.     return $self->{'Mode'};
  795. }
  796.  
  797.  
  798. #==========
  799. sub Rmdir {
  800. #==========
  801.     my($self, $path) = @_;
  802.     return undef unless ref($self);
  803.  
  804.     if($self->{'Type'} ne "FTP" or !defined($self->{'handle'})) {
  805.         $self->{'Error'} = "Rmdir() only on FTP sessions.";
  806.         return undef;
  807.     }
  808.     my $retval = FtpRemoveDirectory($self->{'handle'}, $path);
  809.     $self->{'Error'} = "Can't remove directory." unless defined($retval);
  810.     return $retval;
  811. }
  812. #====================
  813. sub Rd { Rmdir(@_); }
  814. #====================
  815.  
  816.  
  817. #=========
  818. sub Pasv {
  819. #=========
  820.     my($self, $value) = @_;
  821.     return undef unless ref($self);
  822.  
  823.     if(defined($value) and $self->{'Type'} eq "Internet") {
  824.         if($value == 0) {
  825.             $self->{'pasv'} = 0;
  826.         } else {
  827.             $self->{'pasv'} = 1;
  828.         }
  829.     }
  830.     return $self->{'pasv'};
  831. }
  832.  
  833. #=========
  834. sub List {
  835. #=========
  836.     my($self, $pattern, $retmode) = @_;
  837.     return undef unless ref($self);
  838.  
  839.     my $retval = "";
  840.     my $size   = ""; 
  841.     my $attr   = ""; 
  842.     my $ctime  = ""; 
  843.     my $atime  = ""; 
  844.     my $mtime  = "";
  845.     my $csec = 0; my $cmin = 0; my $chou = 0; my $cday = 0; my $cmon = 0; my $cyea = 0;
  846.     my $asec = 0; my $amin = 0; my $ahou = 0; my $aday = 0; my $amon = 0; my $ayea = 0;
  847.     my $msec = 0; my $mmin = 0; my $mhou = 0; my $mday = 0; my $mmon = 0; my $myea = 0;
  848.     my $newhandle = 0;
  849.     my $nextfile  = 1;
  850.     my @results   = ();
  851.     my ($filename, $altname, $file);
  852.   
  853.     if($self->{'Type'} ne "FTP") {
  854.         $self->{'Error'} = "List() only on FTP sessions.";
  855.         return undef;
  856.     }
  857.   
  858.     $pattern = "" unless defined($pattern);
  859.     $retmode = 1  unless defined($retmode);
  860.  
  861.     if($retmode == 2) {
  862.   
  863.         ( $newhandle,$filename, $altname, $size, $attr,         
  864.           $csec, $cmin, $chou, $cday, $cmon, $cyea,
  865.           $asec, $amin, $ahou, $aday, $amon, $ayea,
  866.           $msec, $mmin, $mhou, $mday, $mmon, $myea
  867.         ) = FtpFindFirstFile($self->{'handle'}, $pattern, 0, 0);
  868.     
  869.         if(!$newhandle) {
  870.             $self->{'Error'} = "Can't read FTP directory.";
  871.             return undef;
  872.         } else {
  873.     
  874.             while($nextfile) {
  875.                 $ctime = join(",", ($csec, $cmin, $chou, $cday, $cmon, $cyea));
  876.                 $atime = join(",", ($asec, $amin, $ahou, $aday, $amon, $ayea));
  877.                 $mtime = join(",", ($msec, $mmin, $mhou, $mday, $mmon, $myea));
  878.                 push(@results, $filename, $altname, $size, $attr, $ctime, $atime, $mtime);
  879.         
  880.                 ( $nextfile, $filename, $altname, $size, $attr,
  881.                   $csec, $cmin, $chou, $cday, $cmon, $cyea,
  882.                   $asec, $amin, $ahou, $aday, $amon, $ayea,
  883.                   $msec, $mmin, $mhou, $mday, $mmon, $myea
  884.                 ) = InternetFindNextFile($newhandle);      
  885.         
  886.             }
  887.             InternetCloseHandle($newhandle);
  888.             return @results;
  889.       
  890.         }
  891.     
  892.     } elsif($retmode == 3) {
  893.   
  894.         ( $newhandle,$filename, $altname, $size, $attr,
  895.           $csec, $cmin, $chou, $cday, $cmon, $cyea,
  896.           $asec, $amin, $ahou, $aday, $amon, $ayea,
  897.           $msec, $mmin, $mhou, $mday, $mmon, $myea
  898.         ) = FtpFindFirstFile($self->{'handle'}, $pattern, 0, 0);
  899.     
  900.         if(!$newhandle) {
  901.             $self->{'Error'} = "Can't read FTP directory.";
  902.             return undef;
  903.        
  904.         } else {
  905.      
  906.             while($nextfile) {
  907.                 $ctime = join(",", ($csec, $cmin, $chou, $cday, $cmon, $cyea));
  908.                 $atime = join(",", ($asec, $amin, $ahou, $aday, $amon, $ayea));
  909.                 $mtime = join(",", ($msec, $mmin, $mhou, $mday, $mmon, $myea));
  910.                 $file = { "name"     => $filename,
  911.                           "altname"  => $altname,
  912.                           "size"     => $size,
  913.                           "attr"     => $attr,
  914.                           "ctime"    => $ctime,
  915.                           "atime"    => $atime,
  916.                           "mtime"    => $mtime,
  917.                 };
  918.                 push(@results, $file);
  919.          
  920.                 ( $nextfile, $filename, $altname, $size, $attr,
  921.                   $csec, $cmin, $chou, $cday, $cmon, $cyea,
  922.                   $asec, $amin, $ahou, $aday, $amon, $ayea,
  923.                   $msec, $mmin, $mhou, $mday, $mmon, $myea
  924.                 ) = InternetFindNextFile($newhandle);
  925.          
  926.             }
  927.             InternetCloseHandle($newhandle);
  928.             return @results;
  929.         }
  930.     
  931.     } else {
  932.     
  933.         ($newhandle, $filename) = FtpFindFirstFile($self->{'handle'}, $pattern, 0, 0);
  934.     
  935.         if(!$newhandle) {
  936.             $self->{'Error'} = "Can't read FTP directory.";
  937.             return undef;
  938.       
  939.         } else {
  940.     
  941.             while($nextfile) {
  942.                 push(@results, $filename);
  943.         
  944.                 ($nextfile, $filename) = InternetFindNextFile($newhandle);  
  945.                 # print "List.no more files\n" if !$nextfile;
  946.         
  947.             }
  948.             InternetCloseHandle($newhandle);
  949.             return @results;
  950.         }
  951.     }
  952. }
  953. #====================
  954. sub Ls  { List(@_); }
  955. sub Dir { List(@_); }
  956. #====================
  957.  
  958.  
  959. #=================
  960. sub FileAttrInfo {
  961. #=================
  962.     my($self,$attr) = @_;
  963.     my @attrinfo = ();
  964.     push(@attrinfo, "READONLY")   if $attr & 1;
  965.     push(@attrinfo, "HIDDEN")     if $attr & 2;
  966.     push(@attrinfo, "SYSTEM")     if $attr & 4;
  967.     push(@attrinfo, "DIRECTORY")  if $attr & 16;
  968.     push(@attrinfo, "ARCHIVE")    if $attr & 32;
  969.     push(@attrinfo, "NORMAL")     if $attr & 128;
  970.     push(@attrinfo, "TEMPORARY")  if $attr & 256;
  971.     push(@attrinfo, "COMPRESSED") if $attr & 2048;
  972.     return (wantarray)? @attrinfo : join(" ", @attrinfo);
  973. }
  974.  
  975.  
  976. #===========
  977. sub Binary {
  978. #===========
  979.     my($self) = @_;
  980.     return undef unless ref($self);
  981.  
  982.     if($self->{'Type'} ne "FTP") {
  983.         $self->{'Error'} = "Binary() only on FTP sessions.";
  984.         return undef;
  985.     }
  986.     $self->{'Mode'} = "bin";
  987.     return undef;
  988. }
  989. #======================
  990. sub Bin { Binary(@_); }
  991. #======================
  992.  
  993.  
  994. #==========
  995. sub Ascii {
  996. #==========
  997.     my($self) = @_;
  998.     return undef unless ref($self);
  999.  
  1000.     if($self->{'Type'} ne "FTP") {
  1001.         $self->{'Error'} = "Ascii() only on FTP sessions.";
  1002.         return undef;
  1003.     }
  1004.     $self->{'Mode'} = "asc";
  1005.     return undef;
  1006. }
  1007. #=====================
  1008. sub Asc { Ascii(@_); }
  1009. #=====================
  1010.  
  1011.  
  1012. #========
  1013. sub Get {
  1014. #========
  1015.     my($self, $remote, $local, $overwrite, $flags, $context) = @_;
  1016.     return undef unless ref($self);
  1017.  
  1018.     if($self->{'Type'} ne "FTP") {
  1019.         $self->{'Error'} = "Get() only on FTP sessions.";
  1020.         return undef;
  1021.     }
  1022.     my $mode = ($self->{'Mode'} eq "asc" ? 1 : 2);
  1023.  
  1024.     $remote    = ""      unless defined($remote);
  1025.     $local     = $remote unless defined($local);
  1026.     $overwrite = 0       unless defined($overwrite);
  1027.     $flags     = 0       unless defined($flags);
  1028.     $context   = 0       unless defined($context);
  1029.   
  1030.     my $retval = FtpGetFile($self->{'handle'},
  1031.                             $remote,
  1032.                             $local,
  1033.                             $overwrite,
  1034.                             $flags,
  1035.                             $mode,
  1036.                             $context);
  1037.     $self->{'Error'} = "Can't get file." unless defined($retval);
  1038.     return $retval;
  1039. }
  1040.  
  1041.  
  1042. #===========
  1043. sub Rename {
  1044. #===========
  1045.     my($self, $oldname, $newname) = @_;
  1046.     return undef unless ref($self);
  1047.  
  1048.     if($self->{'Type'} ne "FTP") {
  1049.         $self->{'Error'} = "Rename() only on FTP sessions.";
  1050.         return undef;
  1051.     }
  1052.  
  1053.     my $retval = FtpRenameFile($self->{'handle'}, $oldname, $newname);
  1054.     $self->{'Error'} = "Can't rename file." unless defined($retval);
  1055.     return $retval;
  1056. }
  1057. #======================
  1058. sub Ren { Rename(@_); }
  1059. #======================
  1060.  
  1061.  
  1062. #===========
  1063. sub Delete {
  1064. #===========
  1065.     my($self, $filename) = @_;
  1066.     return undef unless ref($self);
  1067.  
  1068.     if($self->{'Type'} ne "FTP") {
  1069.         $self->{'Error'} = "Delete() only on FTP sessions.";
  1070.         return undef;
  1071.     }
  1072.     my $retval = FtpDeleteFile($self->{'handle'}, $filename);
  1073.     $self->{'Error'} = "Can't delete file." unless defined($retval);
  1074.     return $retval;
  1075. }
  1076. #======================
  1077. sub Del { Delete(@_); }
  1078. #======================
  1079.  
  1080.  
  1081. #========
  1082. sub Put {
  1083. #========
  1084.     my($self, $local, $remote, $context) = @_;
  1085.     return undef unless ref($self);
  1086.  
  1087.     if($self->{'Type'} ne "FTP") {
  1088.         $self->{'Error'} = "Put() only on FTP sessions.";
  1089.         return undef;
  1090.     }
  1091.     my $mode = ($self->{'Mode'} eq "asc" ? 1 : 2);
  1092.  
  1093.     $context = 0 unless defined($context);
  1094.   
  1095.     my $retval = FtpPutFile($self->{'handle'}, $local, $remote, $mode, $context);
  1096.     $self->{'Error'} = "Can't put file." unless defined($retval);
  1097.     return $retval;
  1098. }
  1099.  
  1100.  
  1101. #######################################################################
  1102. # HTTP CLASS METHODS
  1103. #
  1104.  
  1105. #========= ### HTTP CONSTRUCTOR
  1106. sub HTTP {
  1107. #=========
  1108.     my($self, $new, $server, $username, $password, $port, $flags, $context) = @_;    
  1109.     return undef unless ref($self);
  1110.  
  1111.     if(ref($server) and ref($server) eq "HASH") {
  1112.         my $myserver = $server->{'server'};
  1113.         $username    = $server->{'username'};
  1114.         $password    = $password->{'host'};
  1115.         $port        = $server->{'port'};    
  1116.         $flags       = $server->{'flags'};
  1117.         $context     = $server->{'context'};
  1118.         undef $server;
  1119.         $server      = $myserver;
  1120.     }
  1121.  
  1122.     $server   = ""          unless defined($server);
  1123.     $username = "anonymous" unless defined($username);
  1124.     $password = ""          unless defined($username);
  1125.     $port     = 80          unless defined($port);
  1126.     $flags    = 0           unless defined($flags);
  1127.     $context  = 0           unless defined($context);
  1128.   
  1129.     my $newhandle = InternetConnect($self->{'handle'}, $server, $port,
  1130.                                     $username, $password,
  1131.                                     constant("INTERNET_SERVICE_HTTP", 0),
  1132.                                     $flags, $context);
  1133.     if($newhandle) {
  1134.         $self->{'connections'}++;
  1135.         $_[1] = _new($newhandle);
  1136.         $_[1]->{'Type'}     = "HTTP";
  1137.         $_[1]->{'username'} = $username;
  1138.         $_[1]->{'password'} = $password;
  1139.         $_[1]->{'server'}   = $server;
  1140.         $_[1]->{'accept'}   = "text/*\0image/gif\0image/jpeg";
  1141.         return $newhandle;
  1142.     } else {
  1143.         return undef;
  1144.     }
  1145. }
  1146.  
  1147.  
  1148. #================
  1149. sub OpenRequest {
  1150. #================
  1151.     # alternatively to Request:
  1152.     # it creates a new HTTP_Request object
  1153.     # you can act upon it with AddHeader, SendRequest, ReadFile, QueryInfo, Close, ...
  1154.  
  1155.     my($self, $new, $path, $method, $version, $referer, $accept, $flags, $context) = @_;
  1156.     return undef unless ref($self);
  1157.  
  1158.     if($self->{'Type'} ne "HTTP") {
  1159.         $self->{'Error'} = "OpenRequest() only on HTTP sessions.";
  1160.         return undef;
  1161.     }
  1162.  
  1163.     if(ref($path) and ref($path) eq "HASH") {
  1164.         $method    = $path->{'method'};
  1165.         $version   = $path->{'version'};
  1166.         $referer   = $path->{'referer'};
  1167.         $accept    = $path->{'accept'};
  1168.         $flags     = $path->{'flags'};
  1169.         $context   = $path->{'context'};
  1170.         my $mypath = $path->{'path'};
  1171.         undef $path;
  1172.         $path      = $mypath;
  1173.     }
  1174.  
  1175.     $method  = "GET"             unless defined($method);
  1176.     $path    = "/"               unless defined($path);
  1177.     $version = "HTTP/1.0"        unless defined($version); 
  1178.     $referer = ""                unless defined($referer);
  1179.     $accept  = $self->{'accept'} unless defined($accept);
  1180.     $flags   = 0                 unless defined($flags);
  1181.     $context = 0                 unless defined($context);
  1182.   
  1183.     $path = "/".$path if substr($path,0,1) ne "/";  
  1184.   
  1185.     my $newhandle = HttpOpenRequest($self->{'handle'},
  1186.                                     $method,
  1187.                                     $path,
  1188.                                     $version,
  1189.                                     $referer,
  1190.                                     $accept,
  1191.                                     $flags,
  1192.                                     $context);
  1193.     if($newhandle) {
  1194.         $_[1] = _new($newhandle);
  1195.         $_[1]->{'Type'}    = "HTTP_Request";
  1196.         $_[1]->{'method'}  = $method;
  1197.         $_[1]->{'request'} = $path;
  1198.         $_[1]->{'accept'}  = $accept;
  1199.         return $newhandle;
  1200.     } else {
  1201.         return undef;
  1202.     }
  1203. }
  1204.  
  1205. #================
  1206. sub SendRequest {
  1207. #================
  1208.     my($self, $postdata) = @_;
  1209.     return undef unless ref($self);
  1210.  
  1211.     if($self->{'Type'} ne "HTTP_Request") {
  1212.         $self->{'Error'} = "SendRequest() only on HTTP requests.";
  1213.         return undef;
  1214.     }
  1215.   
  1216.     $postdata = "" unless defined($postdata);
  1217.  
  1218.     return HttpSendRequest($self->{'handle'}, "", $postdata);
  1219. }
  1220.  
  1221.  
  1222. #==============
  1223. sub AddHeader {
  1224. #==============
  1225.     my($self, $header, $flags) = @_;
  1226.     return undef unless ref($self);
  1227.   
  1228.     if($self->{'Type'} ne "HTTP_Request") {
  1229.         $self->{'Error'} = "AddHeader() only on HTTP requests.";
  1230.         return undef;
  1231.     }
  1232.   
  1233.     $flags = constant("HTTP_ADDREQ_FLAG_ADD", 0) if (!defined($flags) or $flags == 0);
  1234.  
  1235.     return HttpAddRequestHeaders($self->{'handle'}, $header, $flags);
  1236. }
  1237.  
  1238.  
  1239. #==============
  1240. sub QueryInfo {
  1241. #==============
  1242.     my($self, $header, $flags) = @_;
  1243.     return undef unless ref($self);
  1244.  
  1245.     if($self->{'Type'} ne "HTTP_Request") {
  1246.         $self->{'Error'}="QueryInfo() only on HTTP requests.";
  1247.         return undef;
  1248.     }
  1249.   
  1250.     $flags = constant("HTTP_QUERY_CUSTOM", 0) if (!defined($flags) and defined($header));
  1251.     my @queryresult = HttpQueryInfo($self->{'handle'}, $flags, $header);
  1252.     return (wantarray)? @queryresult : join(" ", @queryresult);
  1253. }
  1254.  
  1255.  
  1256. #============
  1257. sub Request {
  1258. #============
  1259.     # HttpOpenRequest+HttpAddHeaders+HttpSendRequest+InternetReadFile+HttpQueryInfo
  1260.     my($self, $path, $method, $version, $referer, $accept, $flags, $postdata) = @_;
  1261.     return undef unless ref($self);
  1262.  
  1263.     if($self->{'Type'} ne "HTTP") {
  1264.         $self->{'Error'} = "Request() only on HTTP sessions.";
  1265.         return undef;
  1266.     }
  1267.  
  1268.     if(ref($path) and ref($path) eq "HASH") {
  1269.         $method    = $path->{'method'};
  1270.         $version   = $path->{'version'};
  1271.         $referer   = $path->{'referer'};
  1272.         $accept    = $path->{'accept'};
  1273.         $flags     = $path->{'flags'};
  1274.         $postdata  = $path->{'postdata'};
  1275.         my $mypath = $path->{'path'};
  1276.         undef $path;
  1277.         $path      = $mypath;
  1278.     }
  1279.  
  1280.     my $content     = "";
  1281.     my $result      = "";
  1282.     my @queryresult = ();
  1283.     my $statuscode  = "";
  1284.     my $headers     = "";
  1285.   
  1286.     $path     = "/"               unless defined($path);
  1287.     $method   = "GET"             unless defined($method);
  1288.     $version  = "HTTP/1.0"        unless defined($version); 
  1289.     $referer  = ""                unless defined($referer);
  1290.     $accept   = $self->{'accept'} unless defined($accept);
  1291.     $flags    = 0                 unless defined($flags);
  1292.     $postdata = ""                unless defined($postdata);
  1293.  
  1294.     $path = "/".$path if substr($path,0,1) ne "/";  
  1295.   
  1296.     my $newhandle = HttpOpenRequest($self->{'handle'},
  1297.                                     $method,
  1298.                                     $path,
  1299.                                     $version,
  1300.                                     $referer,
  1301.                                     $accept,
  1302.                                     $flags,
  1303.                     0);
  1304.  
  1305.     if($newhandle) {
  1306.  
  1307.         $result = HttpSendRequest($newhandle, "", $postdata);
  1308.  
  1309.         if(defined($result)) {
  1310.             $statuscode = HttpQueryInfo($newhandle,
  1311.                                         constant("HTTP_QUERY_STATUS_CODE", 0), "");
  1312.             $headers = HttpQueryInfo($newhandle,
  1313.                                      constant("HTTP_QUERY_RAW_HEADERS_CRLF", 0), "");
  1314.             $content = ReadEntireFile($newhandle);
  1315.                
  1316.             InternetCloseHandle($newhandle);
  1317.       
  1318.             return($statuscode, $headers, $content);
  1319.         } else {
  1320.             return undef;
  1321.         }
  1322.     } else {
  1323.         return undef;
  1324.     }
  1325. }
  1326.  
  1327.  
  1328. #######################################################################
  1329. # END OF THE PUBLIC METHODS
  1330. #
  1331.  
  1332.  
  1333. #========= ### SUB-CLASSES CONSTRUCTOR
  1334. sub _new {
  1335. #=========
  1336.     my $self = {};
  1337.     if ($_[0]) {
  1338.         $self->{'handle'} = $_[0];
  1339.         bless $self;
  1340.     } else {
  1341.         undef($self);
  1342.     }
  1343.     $self;
  1344. }
  1345.  
  1346.  
  1347. #============ ### CLASS DESTRUCTOR
  1348. sub DESTROY {
  1349. #============
  1350.     my($self) = @_;
  1351.     # print "Closing handle $self->{'handle'}...\n";
  1352.     InternetCloseHandle($self->{'handle'});
  1353.     # [dada] rest in peace
  1354. }
  1355.  
  1356.  
  1357. #=============
  1358. sub callback {
  1359. #=============
  1360.     my($name, $status, $info) = @_;
  1361.     $callback_code{$name} = $status;
  1362.     $callback_info{$name} = $info;
  1363. }
  1364.  
  1365. #######################################################################
  1366. # dynamically load in the Internet.pll module.
  1367. #
  1368.  
  1369. bootstrap Win32::Internet;
  1370.  
  1371. # Preloaded methods go here.
  1372.  
  1373. #Currently Autoloading is not implemented in Perl for win32
  1374. # Autoload methods go after __END__, and are processed by the autosplit program.
  1375.  
  1376. 1;
  1377. __END__
  1378.  
  1379. =head1 NAME
  1380.  
  1381. Win32::Internet - Access to WININET.DLL functions
  1382.  
  1383. =head1 INTRODUCTION
  1384.  
  1385. This extension to Perl implements the Win32 Internet APIs (found in
  1386. F<WININET.DLL>). They give a complete support for HTTP, FTP and GOPHER
  1387. connections.
  1388.  
  1389. See the L<"Version History"> and the L<"Functions Table"> for a list
  1390. of the currently supported features. You should also get a copy of the
  1391. L<"Microsoft Win32 Internet Functions"> documentation.
  1392.  
  1393. =head1 REFERENCE
  1394.  
  1395. To use this module, first add the following line at the beginning of
  1396. your script:
  1397.  
  1398.     use Win32::Internet;
  1399.  
  1400. Then you have to open an Internet connection with this command:
  1401.  
  1402.     $Connection = new Win32::Internet();
  1403.  
  1404. This is required to use any of the function of this module.  It will
  1405. create an Internet object in Perl on which you can act upon with the
  1406. L<"General Internet Functions"> explained later.
  1407.  
  1408. The objects available are:
  1409.  
  1410. =over
  1411.  
  1412. =item *
  1413.  
  1414. Internet connections (the main object, see C<new>)
  1415.  
  1416. =item *
  1417.  
  1418. URLs (see C<OpenURL>)
  1419.  
  1420. =item *
  1421.  
  1422. FTP sessions (see C<FTP>)
  1423.  
  1424. =item *
  1425.  
  1426. HTTP sessions (see C<HTTP>)
  1427.  
  1428. =item *
  1429.  
  1430. HTTP requests (see C<OpenRequest>)
  1431.  
  1432. =back
  1433.  
  1434. As in the good Perl tradition, there are in this extension different
  1435. ways to do the same thing; there are, in fact, different levels of
  1436. implementation of the Win32 Internet Functions.  Some routines use
  1437. several Win32 API functions to perform a complex task in a single
  1438. call; they are simpler to use, but of course less powerful.
  1439.  
  1440. There are then other functions that implement nothing more and nothing
  1441. less than the corresponding API function, so you can use all of their
  1442. power, but with some additional programming steps.
  1443.  
  1444. To make an example, there is a function called C<FetchURL> that you
  1445. can use to fetch the content of any HTTP, FTP or GOPHER URL with this
  1446. simple commands:
  1447.  
  1448.     $INET = new Win32::Internet();
  1449.     $file = $INET->FetchURL("http://www.yahoo.com");
  1450.  
  1451. You can have the same result (and this is actually what is done by
  1452. C<FetchURL>) this way:
  1453.  
  1454.     $INET = new Win32::Internet();
  1455.     $URL = $INET->OpenURL("http://www.yahoo.com");
  1456.     $file = $URL->ReadFile();
  1457.     $URL->Close();
  1458.  
  1459. Or, you can open a complete HTTP session:
  1460.  
  1461.     $INET = new Win32::Internet();
  1462.     $HTTP = $INET->HTTP("www.yahoo.com", "anonymous", "dada@divinf.it");
  1463.     ($statuscode, $headers, $file) = $HTTP->Request("/");
  1464.     $HTTP->Close();
  1465.  
  1466. Finally, you can choose to manage even the HTTP request:
  1467.  
  1468.     $INET = new Win32::Internet();
  1469.     $HTTP = $INET->HTTP("www.yahoo.com", "anonymous", "dada@divinf.it");
  1470.     $HTTP->OpenRequest($REQ, "/");
  1471.     $REQ->AddHeader("If-Modified-Since: Saturday, 16-Nov-96 15:58:50 GMT");
  1472.     $REQ->SendRequest();
  1473.     $statuscode = $REQ->QueryInfo("",HTTP_QUERY_STATUS_CODE);
  1474.     $lastmodified = $REQ->QueryInfo("Last-Modified");
  1475.     $file = $REQ->ReadEntireFile();
  1476.     $REQ->Close();
  1477.     $HTTP->Close();
  1478.  
  1479. To open and control a complete FTP session, type:
  1480.  
  1481.     $Connection->FTP($Session, "ftp://ftp.activeware.com", "anonymous", "dada\@divinf.it");
  1482.  
  1483. This will create an FTP object in Perl to which you can apply the L<"FTP
  1484. functions"> provided by the package:
  1485.  
  1486.     $Session->Cd("/ntperl/perl5.001m/CurrentBuild");
  1487.     $Session->Ascii();
  1488.     $Session->Get("110-i86.zip");
  1489.     $Session->Close();
  1490.  
  1491. For a more complete example, see the TEST.PL file that comes with the
  1492. package.
  1493.  
  1494. =head2 General Internet Functions
  1495.  
  1496. B<General Note>
  1497.  
  1498. All methods assume that you have the line:
  1499.  
  1500.     use Win32::Internet;
  1501.  
  1502. somewhere before the method calls, and that you have an Internet
  1503. object called $INET which was created using this call:
  1504.  
  1505.     $INET = new Win32::Internet();
  1506.  
  1507. See C<new> for more information.
  1508.  
  1509. B<Methods>
  1510.  
  1511. =over
  1512.  
  1513. =item CanonicalizeURL URL, [flags]
  1514.  
  1515. Converts a URL to a canonical format, which includes converting unsafe
  1516. characters to escape sequences.  Returns the canonicalized URL or
  1517. C<undef> on errors.  For the possible values of I<flags>, refer to the
  1518. L<"Microsoft Win32 Internet Functions"> document.  See also
  1519. C<CombineURL> and C<OpenURL>.
  1520.  
  1521. Example:
  1522.  
  1523.     $cURL = $INET->CanonicalizeURL($URL);
  1524.     $URL = $INET->CanonicalizeURL($cURL, ICU_DECODE);
  1525.  
  1526. =item Close
  1527.  
  1528. =item Close object
  1529.  
  1530. Closes an Internet connection.  This can be applied to any
  1531. Win32::Internet object (Internet connections, URLs, FTP sessions,
  1532. etc.).  Note that it is not "strictly" required to close the
  1533. connections you create, since the Win32::Internet objects are
  1534. automatically closed when the program ends (or when you elsehow
  1535. destroy such an object).
  1536.  
  1537. Example:
  1538.  
  1539.     $INET->Close();
  1540.     $FTP->Close();
  1541.     $INET->Close($FTP); # same as above...
  1542.  
  1543. =item CombineURL baseURL, relativeURL, [flags]
  1544.  
  1545. Combines a base and relative URL into a single URL.  Returns the
  1546. (canonicalized) combined URL or C<undef> on errors.  For the possible
  1547. values of I<flags>, refer to the L<"Microsoft Win32 Internet
  1548. Functions"> document.  See also C<CombineURL> and C<OpenURL>.
  1549.  
  1550. Example:
  1551.  
  1552.     $URL = $INET->CombineURL("http://www.divinf.it/dada/perl/internet", "..");
  1553.  
  1554. =item ConnectBackoff [value]
  1555.  
  1556. Reads or sets the delay value, in milliseconds, to wait between
  1557. connection retries.  If no I<value> parameter is specified, the
  1558. current value is returned; otherwise, the delay between retries is set
  1559. to I<value>.  See also C<ConnectTimeout>, C<ConnectRetries>,
  1560. C<QueryOption> and C<SetOption>.
  1561.  
  1562. Example:
  1563.  
  1564.     $HTTP->ConnectBackoff(2000);
  1565.     $backoff = $HTTP->ConnectBackoff();
  1566.  
  1567. =item ConnectRetries [value]
  1568.  
  1569. Reads or sets the number of times a connection is retried before
  1570. considering it failed.  If no I<value> parameter is specified, the
  1571. current value is returned; otherwise, the number of retries is set to
  1572. I<value>.  The default value for C<ConnectRetries> is 5.  See also
  1573. C<ConnectBackoff>, C<ConnectTimeout>, C<QueryOption> and C<SetOption>.
  1574.  
  1575. Example:
  1576.  
  1577.     $HTTP->ConnectRetries(20);
  1578.     $retries = $HTTP->ConnectRetries();
  1579.  
  1580. =item ConnectTimeout [value]
  1581.  
  1582. Reads or sets the timeout value (in milliseconds) before a connection
  1583. is considered failed.  If no I<value> parameter is specified, the
  1584. current value is returned; otherwise, the timeout is set to I<value>.
  1585. The default value for C<ConnectTimeout> is infinite.  See also
  1586. C<ConnectBackoff>, C<ConnectRetries>, C<QueryOption> and C<SetOption>.
  1587.  
  1588. Example:
  1589.  
  1590.     $HTTP->ConnectTimeout(10000);
  1591.     $timeout = $HTTP->ConnectTimeout();
  1592.  
  1593. =item ControlReceiveTimeout [value]
  1594.  
  1595. Reads or sets the timeout value (in milliseconds) to use for non-data
  1596. (control) receive requests before they are canceled.  Currently, this
  1597. value has meaning only for C<FTP> sessions.  If no I<value> parameter
  1598. is specified, the current value is returned; otherwise, the timeout is
  1599. set to I<value>.  The default value for C<ControlReceiveTimeout> is
  1600. infinite.  See also C<ControlSendTimeout>, C<QueryOption> and
  1601. C<SetOption>.
  1602.  
  1603. Example:
  1604.  
  1605.     $HTTP->ControlReceiveTimeout(10000);
  1606.     $timeout = $HTTP->ControlReceiveTimeout();
  1607.  
  1608. =item ControlSendTimeout [value]
  1609.  
  1610. Reads or sets the timeout value (in milliseconds) to use for non-data
  1611. (control) send requests before they are canceled.  Currently, this
  1612. value has meaning only for C<FTP> sessions.  If no I<value> parameter
  1613. is specified, the current value is returned; otherwise, the timeout is
  1614. set to I<value>.  The default value for C<ControlSendTimeout> is
  1615. infinite.  See also C<ControlReceiveTimeout>, C<QueryOption> and
  1616. C<SetOption>.
  1617.  
  1618. Example:
  1619.  
  1620.     $HTTP->ControlSendTimeout(10000);
  1621.     $timeout = $HTTP->ControlSendTimeout();
  1622.  
  1623. =item CrackURL URL, [flags]
  1624.  
  1625. Splits an URL into its component parts and returns them in an array.
  1626. Returns C<undef> on errors, otherwise the array will contain the
  1627. following values: I<scheme, host, port, username, password, path,
  1628. extrainfo>.
  1629.  
  1630. For example, the URL "http://www.divinf.it/index.html#top" can be
  1631. splitted in:
  1632.  
  1633.     http, www.divinf.it, 80, anonymous, dada@divinf.it, /index.html, #top
  1634.  
  1635. If you don't specify a I<flags> parameter, ICU_ESCAPE will be used by
  1636. default; for the possible values of I<flags> refer to the L<"Microsoft
  1637. Win32 Internet Functions"> documentation.  See also C<CreateURL>.
  1638.  
  1639. Example:
  1640.  
  1641.     @parts=$INET->CrackURL("http://www.activeware.com");
  1642.     ($scheme, $host, $port, $user, $pass, $path, $extra) =
  1643.          $INET->CrackURL("http://www.divinf.it:80/perl-win32/index.sht#feedback");
  1644.  
  1645. =item CreateURL scheme, hostname, port, username, password, path, extrainfo, [flags]
  1646.  
  1647. =item CreateURL hashref, [flags]
  1648.  
  1649. Creates a URL from its component parts.  Returns C<undef> on errors,
  1650. otherwise the created URL.
  1651.  
  1652. If you pass I<hashref> (a reference to an hash array), the following
  1653. values are taken from the array:
  1654.  
  1655.     %hash=(
  1656.       "scheme"    => "scheme",
  1657.       "hostname"  => "hostname",
  1658.       "port"      => port,
  1659.       "username"  => "username",
  1660.       "password"  => "password",
  1661.       "path"      => "path",
  1662.       "extrainfo" => "extrainfo",
  1663.     );
  1664.  
  1665. If you don't specify a I<flags> parameter, ICU_ESCAPE will be used by
  1666. default; for the other possible values of I<flags> refer to the
  1667. L<"Microsoft Win32 Internet Functions"> documentation.  See also
  1668. C<CrackURL>.
  1669.  
  1670. Example:
  1671.  
  1672.     $URL=$I->CreateURL("http", "www.divinf.it", 80, "", "", "/perl-win32/index.sht", "#feedback");
  1673.     $URL=$I->CreateURL(\%params);
  1674.  
  1675. =item DataReceiveTimeout [value]
  1676.  
  1677. Reads or sets the timeout value (in milliseconds) to use for data
  1678. receive requests before they are canceled.  If no I<value> parameter
  1679. is specified, the current value is returned; otherwise, the timeout is
  1680. set to I<value>.  The default value for DataReceiveTimeout is
  1681. infinite.  See also C<DataSendTimeout>, C<QueryOption> and
  1682. C<SetOption>.
  1683.  
  1684. Example:
  1685.  
  1686.     $HTTP->DataReceiveTimeout(10000);
  1687.     $timeout = $HTTP->DataReceiveTimeout();
  1688.  
  1689. =item DataSendTimeout [value]
  1690.  
  1691. Reads or sets the timeout value (in milliseconds) to use for data send
  1692. requests before they are canceled.  If no I<value> parameter is
  1693. specified, the current value is returned; otherwise, the timeout is
  1694. set to I<value>.  The default value for DataSendTimeout is infinite.
  1695. See also C<DataReceiveTimeout>, C<QueryOption> and C<SetOption>.
  1696.  
  1697. Example:
  1698.  
  1699.     $HTTP->DataSendTimeout(10000);
  1700.     $timeout = $HTTP->DataSendTimeout();
  1701.  
  1702. =item Error
  1703.  
  1704. Returns the last recorded error in the form of an array or string
  1705. (depending upon the context) containing the error number and an error
  1706. description.  Can be applied on any Win32::Internet object (FTP
  1707. sessions, etc.).  There are 3 types of error you can encounter; they
  1708. are recognizable by the error number returned:
  1709.  
  1710. =over
  1711.  
  1712. =item * -1
  1713.  
  1714. A "trivial" error has occurred in the package.  For example, you tried
  1715. to use a method on the wrong type of object.
  1716.  
  1717. =item * 1 .. 11999
  1718.  
  1719. A generic error has occurred and the Win32::GetLastError error message
  1720. is returned.
  1721.  
  1722. =item * 12000 and higher
  1723.  
  1724. An Internet error has occurred; the extended Win32 Internet API error
  1725. message is returned.
  1726.  
  1727. =back
  1728.  
  1729. See also C<GetResponse>.
  1730.  
  1731. Example:
  1732.  
  1733.     die $INET->Error(), qq(\n);
  1734.     ($ErrNum, $ErrText) = $INET->Error();
  1735.  
  1736. =item FetchURL URL
  1737.  
  1738. Fetch the content of an HTTP, FTP or GOPHER URL.  Returns the content
  1739. of the file read (or C<undef> if there was an error and nothing was
  1740. read).  See also C<OpenURL> and C<ReadFile>.
  1741.  
  1742. Example:
  1743.  
  1744.     $file = $INET->FetchURL("http://www.yahoo.com/");
  1745.     $file = $INET->FetchURL("ftp://www.activeware.com/contrib/internet.zip");
  1746.  
  1747. =item FTP ftpobject, server, username, password, [port, pasv, context]
  1748.  
  1749. =item FTP ftpobject, hashref
  1750.  
  1751. Opens an FTP connection to server logging in with the given
  1752. I<username> and I<password>.
  1753.  
  1754. The parameters and their values are:
  1755.  
  1756. =over
  1757.  
  1758. =item * server
  1759.  
  1760. The server to connect to.  Default: I<none>.
  1761.  
  1762. =item * username
  1763.  
  1764. The username used to login to the server.  Default: anonymous.
  1765.  
  1766. =item * password
  1767.  
  1768. The password used to login to the server.  Default: I<none>.
  1769.  
  1770. =item * port
  1771.  
  1772. The port of the FTP service on the server.  Default: 21.
  1773.  
  1774. =item * pasv
  1775.  
  1776. If it is a value other than 0, use passive transfer mode.  Default is
  1777. taken from the parent Internet connection object; you can set this
  1778. value with the C<Pasv> method.
  1779.  
  1780. =item * context
  1781.  
  1782. A number to identify this operation if it is asynchronous.  See
  1783. C<SetStatusCallback> and C<GetStatusCallback> for more info on
  1784. asynchronous operations.  Default: I<none>.
  1785.  
  1786. =back
  1787.  
  1788. If you pass I<hashref> (a reference to an hash array), the following
  1789. values are taken from the array:
  1790.  
  1791.     %hash=(
  1792.       "server"   => "server",
  1793.       "username" => "username",
  1794.       "password" => "password",
  1795.       "port"     => port,
  1796.       "pasv"     => pasv,
  1797.       "context"  => context,
  1798.     );
  1799.  
  1800. This method returns C<undef> if the connection failed, a number
  1801. otherwise.  You can then call any of the L<"FTP functions"> as methods
  1802. of the newly created I<ftpobject>.
  1803.  
  1804. Example:
  1805.  
  1806.     $result = $INET->FTP($FTP, "ftp.activeware.com", "anonymous", "dada\@divinf.it");
  1807.     # and then for example...
  1808.     $FTP->Cd("/ntperl/perl5.001m/CurrentBuild");
  1809.  
  1810.     $params{"server"} = "ftp.activeware.com";
  1811.     $params{"password"} = "dada\@divinf.it";
  1812.     $params{"pasv"} = 0;
  1813.     $result = $INET->FTP($FTP,\%params);
  1814.  
  1815. =item GetResponse
  1816.  
  1817. Returns the text sent by a remote server in response to the last
  1818. function executed.  It applies on any Win32::Internet object,
  1819. particularly of course on L<FTP sessions|"FTP functions">.  See also
  1820. the C<Error> function.
  1821.  
  1822. Example:
  1823.  
  1824.     print $INET->GetResponse();
  1825.     $INET->FTP($FTP, "ftp.activeware.com", "anonymous", "dada\@divinf.it");
  1826.     print $FTP->GetResponse();
  1827.  
  1828. =item GetStatusCallback context
  1829.  
  1830. Returns information about the progress of the asynchronous operation
  1831. identified by I<context>; those informations consist of two values: a
  1832. status code (one of the INTERNET_STATUS_* L<"Constants">) and an
  1833. additional value depending on the status code; for example, if the
  1834. status code returned is INTERNET_STATUS_HANDLE_CREATED, the second
  1835. value will hold the handle just created.  For more informations on
  1836. those values, please refer to the L<"Microsoft Win32 Internet
  1837. Functions"> documentation.  See also C<SetStatusCallback>.
  1838.  
  1839. Example:
  1840.  
  1841.     ($status, $info) = $INET->GetStatusCallback(1);
  1842.  
  1843. =item HTTP httpobject, server, username, password, [port, flags, context]
  1844.  
  1845. =item HTTP httpobject, hashref
  1846.  
  1847. Opens an HTTP connection to I<server> logging in with the given
  1848. I<username> and I<password>.
  1849.  
  1850. The parameters and their values are:
  1851.  
  1852. =over
  1853.  
  1854. =item * server
  1855.  
  1856. The server to connect to.  Default: I<none>.
  1857.  
  1858. =item * username
  1859.  
  1860. The username used to login to the server.  Default: anonymous.
  1861.  
  1862. =item * password
  1863.  
  1864. The password used to login to the server.  Default: I<none>.
  1865.  
  1866. =item * port
  1867.  
  1868. The port of the HTTP service on the server.  Default: 80.
  1869.  
  1870. =item * flags
  1871.  
  1872. Additional flags affecting the behavior of the function.  Default:
  1873. I<none>.
  1874.  
  1875. =item * context
  1876.  
  1877. A number to identify this operation if it is asynchronous.  See
  1878. C<SetStatusCallback> and C<GetStatusCallback> for more info on
  1879. asynchronous operations.  Default: I<none>.
  1880.  
  1881. =back
  1882.  
  1883. Refer to the L<"Microsoft Win32 Internet Functions"> documentation for
  1884. more details on those parameters.
  1885.  
  1886. If you pass I<hashref> (a reference to an hash array), the following
  1887. values are taken from the array:
  1888.  
  1889.     %hash=(
  1890.       "server"   => "server",
  1891.       "username" => "username",
  1892.       "password" => "password",
  1893.       "port"     => port,
  1894.       "flags"    => flags,
  1895.       "context"  => context,
  1896.     );
  1897.  
  1898. This method returns C<undef> if the connection failed, a number
  1899. otherwise.  You can then call any of the L<"HTTP functions"> as
  1900. methods of the newly created I<httpobject>.
  1901.  
  1902. Example:
  1903.  
  1904.     $result = $INET->HTTP($HTTP,"www.activeware.com","anonymous","dada\@divinf.it");
  1905.     # and then for example...
  1906.     ($statuscode, $headers, $file) = $HTTP->Request("/gifs/camel.gif");
  1907.  
  1908.     $params{"server"} = "www.activeware.com";
  1909.     $params{"password"} = "dada\@divinf.it";
  1910.     $params{"flags"} = INTERNET_FLAG_RELOAD;
  1911.     $result = $INET->HTTP($HTTP,\%params);
  1912.  
  1913. =item new Win32::Internet [useragent, opentype, proxy, proxybypass, flags]
  1914.  
  1915. =item new Win32::Internet [hashref]
  1916.  
  1917. Creates a new Internet object and initializes the use of the Internet
  1918. functions; this is required before any of the functions of this
  1919. package can be used.  Returns C<undef> if the connection fails, a number
  1920. otherwise.  The parameters and their values are:
  1921.  
  1922. =over
  1923.  
  1924. =item * useragent
  1925.  
  1926. The user agent passed to HTTP requests.  See C<OpenRequest>.  Default:
  1927. Perl-Win32::Internet/I<version>.
  1928.  
  1929. =item * opentype
  1930.  
  1931. How to access to the Internet (eg. directly or using a proxy).
  1932. Default: INTERNET_OPEN_TYPE_DIRECT.
  1933.  
  1934. =item * proxy
  1935.  
  1936. Name of the proxy server (or servers) to use.  Default: I<none>.
  1937.  
  1938. =item * proxybypass
  1939.  
  1940. Optional list of host names or IP addresses, or both, that are known
  1941. locally.  Default: I<none>.
  1942.  
  1943. =item * flags
  1944.  
  1945. Additional flags affecting the behavior of the function.  Default:
  1946. I<none>.
  1947.  
  1948. =back
  1949.  
  1950. Refer to the L<"Microsoft Win32 Internet Functions"> documentation for
  1951. more details on those parameters.  If you pass I<hashref> (a reference to
  1952. an hash array), the following values are taken from the array:
  1953.  
  1954.     %hash=(
  1955.       "useragent"   => "useragent",
  1956.       "opentype"    => "opentype",
  1957.       "proxy"       => "proxy",
  1958.       "proxybypass" => "proxybypass",
  1959.       "flags"       => flags,
  1960.     );
  1961.  
  1962. Example:
  1963.  
  1964.     $INET = new Win32::Internet();
  1965.     die qq(Cannot connect to Internet...\n) if ! $INET;
  1966.  
  1967.     $INET = new Win32::Internet("Mozilla/3.0", INTERNET_OPEN_TYPE_PROXY, "www.microsoft.com", "");
  1968.  
  1969.     $params{"flags"} = INTERNET_FLAG_ASYNC;
  1970.     $INET = new Win32::Internet(\%params);
  1971.  
  1972. =item OpenURL urlobject, URL
  1973.  
  1974. Opens a connection to an HTTP, FTP or GOPHER Uniform Resource Location
  1975. (URL).  Returns C<undef> on errors or a number if the connection was
  1976. succesful.  You can then retrieve the URL content by applying the
  1977. methods C<QueryDataAvailable> and C<ReadFile> on the newly created
  1978. I<urlobject>.  See also C<FetchURL>.
  1979.  
  1980. Example:
  1981.  
  1982.     $INET->OpenURL($URL, "http://www.yahoo.com/");
  1983.     $bytes = $URL->QueryDataAvailable();
  1984.     $file = $URL->ReadEntireFile();
  1985.     $URL->Close();
  1986.  
  1987. =item Password [password]
  1988.  
  1989. Reads or sets the password used for an C<FTP> or C<HTTP> connection.
  1990. If no I<password> parameter is specified, the current value is
  1991. returned; otherwise, the password is set to I<password>.  See also
  1992. C<Username>, C<QueryOption> and C<SetOption>.
  1993.  
  1994. Example:
  1995.  
  1996.     $HTTP->Password("splurfgnagbxam");
  1997.     $password = $HTTP->Password();
  1998.  
  1999. =item QueryDataAvailable
  2000.  
  2001. Returns the number of bytes of data that are available to be read
  2002. immediately by a subsequent call to C<ReadFile> (or C<undef> on
  2003. errors).  Can be applied to URL or HTTP request objects.  See
  2004. C<OpenURL> or C<OpenRequest>.
  2005.  
  2006. Example:
  2007.  
  2008.     $INET->OpenURL($URL, "http://www.yahoo.com/");
  2009.     $bytes = $URL->QueryDataAvailable();
  2010.  
  2011. =item QueryOption option
  2012.  
  2013. Queries an Internet option.  For the possible values of I<option>,
  2014. refer to the L<"Microsoft Win32 Internet Functions"> document.  See
  2015. also C<SetOption>.
  2016.  
  2017. Example:
  2018.  
  2019.     $value = $INET->QueryOption(INTERNET_OPTION_CONNECT_TIMEOUT);
  2020.     $value = $HTTP->QueryOption(INTERNET_OPTION_USERNAME);
  2021.  
  2022. =item ReadEntireFile
  2023.  
  2024. Reads all the data available from an opened URL or HTTP request
  2025. object.  Returns what have been read or C<undef> on errors.  See also
  2026. C<OpenURL>, C<OpenRequest> and C<ReadFile>.
  2027.  
  2028. Example:
  2029.  
  2030.     $INET->OpenURL($URL, "http://www.yahoo.com/");
  2031.     $file = $URL->ReadEntireFile();
  2032.  
  2033. =item ReadFile bytes
  2034.  
  2035. Reads I<bytes> bytes of data from an opened URL or HTTP request
  2036. object.  Returns what have been read or C<undef> on errors.  See also
  2037. C<OpenURL>, C<OpenRequest>, C<QueryDataAvailable> and
  2038. C<ReadEntireFile>.
  2039.  
  2040. B<Note:> be careful to keep I<bytes> to an acceptable value (eg.  don't
  2041. tell him to swallow megabytes at once...).  C<ReadEntireFile> in fact
  2042. uses C<QueryDataAvailable> and C<ReadFile> in a loop to read no more
  2043. than 16k at a time.
  2044.  
  2045. Example:
  2046.  
  2047.     $INET->OpenURL($URL, "http://www.yahoo.com/");
  2048.     $chunk = $URL->ReadFile(16000);
  2049.  
  2050. =item SetOption option, value
  2051.  
  2052. Sets an Internet option.  For the possible values of I<option>, refer to
  2053. the L<"Microsoft Win32 Internet Functions"> document.  See also
  2054. C<QueryOption>.
  2055.  
  2056. Example:
  2057.  
  2058.     $INET->SetOption(INTERNET_OPTION_CONNECT_TIMEOUT,10000);
  2059.     $HTTP->SetOption(INTERNET_OPTION_USERNAME,"dada");
  2060.  
  2061. =item SetStatusCallback
  2062.  
  2063. Initializes the callback routine used to return data about the
  2064. progress of an asynchronous operation.
  2065.  
  2066. Example:
  2067.  
  2068.     $INET->SetStatusCallback();
  2069.  
  2070. This is one of the step required to perform asynchronous operations;
  2071. the complete procedure is:
  2072.  
  2073.     # use the INTERNET_FLAG_ASYNC when initializing
  2074.     $params{'flags'}=INTERNET_FLAG_ASYNC;
  2075.     $INET = new Win32::Internet(\%params);
  2076.  
  2077.     # initialize the callback routine
  2078.     $INET->SetStatusCallback();
  2079.  
  2080.     # specify the context parameter (the last 1 in this case)
  2081.     $INET->HTTP($HTTP, "www.yahoo.com", "anonymous", "dada\@divinf.it", 80, 0, 1);
  2082.  
  2083. At this point, control returns immediately to Perl and $INET->Error()
  2084. will return 997, which means an asynchronous I/O operation is
  2085. pending.  Now, you can call
  2086.  
  2087.     $HTTP->GetStatusCallback(1);
  2088.  
  2089. in a loop to verify what's happening; see also C<GetStatusCallback>.
  2090.  
  2091. =item TimeConvert time
  2092.  
  2093. =item TimeConvert seconds, minute, hours, day, month, year,
  2094.                   day_of_week, RFC
  2095.  
  2096. The first form takes a HTTP date/time string and returns the date/time
  2097. converted in the following array: I<seconds, minute, hours, day,
  2098. month, year, day_of_week>.
  2099.  
  2100. The second form does the opposite (or at least it should, because
  2101. actually seems to be malfunctioning): it takes the values and returns
  2102. an HTTP date/time string, in the RFC format specified by the I<RFC>
  2103. parameter (OK, I didn't find yet any accepted value in the range
  2104. 0..2000, let me know if you have more luck with it).
  2105.  
  2106. Example:
  2107.  
  2108.     ($sec, $min, $hour, $day, $mday, $year, $wday) =
  2109.        $INET->TimeConvert("Sun, 26 Jan 1997 20:01:52 GMT");
  2110.  
  2111.     # the opposite DOESN'T WORK! which value should $RFC have???
  2112.     $time = $INET->TimeConvert(52, 1, 20, 26, 1, 1997, 0, $RFC);
  2113.  
  2114. =item UserAgent [name]
  2115.  
  2116. Reads or sets the user agent used for HTTP requests.  If no I<name>
  2117. parameter is specified, the current value is returned; otherwise, the
  2118. user agent is set to I<name>.  See also C<QueryOption> and
  2119. C<SetOption>.
  2120.  
  2121. Example:
  2122.  
  2123.     $INET->UserAgent("Mozilla/3.0");
  2124.     $useragent = $INET->UserAgent();
  2125.  
  2126. =item Username [name]
  2127.  
  2128. Reads or sets the username used for an C<FTP> or C<HTTP> connection.
  2129. If no I<name> parameter is specified, the current value is returned;
  2130. otherwise, the username is set to I<name>.  See also C<Password>,
  2131. C<QueryOption> and SetOption.
  2132.  
  2133. Example:
  2134.  
  2135.     $HTTP->Username("dada");
  2136.     $username = $HTTP->Username();
  2137.  
  2138. =item Version
  2139.  
  2140. Returns the version numbers for the Win32::Internet package and the
  2141. WININET.DLL version, as an array or string, depending on the context.
  2142. The string returned will contain "package_version/DLL_version", while
  2143. the array will contain: "package_version", "DLL_version".
  2144.  
  2145. Example:
  2146.  
  2147.     $version = $INET->Version(); # should return "0.06/4.70.1215"
  2148.     @version = $INET->Version(); # should return ("0.06", "4.70.1215")
  2149.  
  2150. =back
  2151.  
  2152.  
  2153. =head2 FTP Functions
  2154.  
  2155. B<General Note>
  2156.  
  2157. All methods assume that you have the following lines:
  2158.  
  2159.     use Win32::Internet;
  2160.     $INET = new Win32::Internet();
  2161.     $INET->FTP($FTP, "hostname", "username", "password");
  2162.  
  2163. somewhere before the method calls; in other words, we assume that you
  2164. have an Internet object called $INET and an open FTP session called
  2165. $FTP.
  2166.  
  2167. See C<new> and C<FTP> for more information.
  2168.  
  2169.  
  2170. B<Methods>
  2171.  
  2172. =over
  2173.  
  2174. =item Ascii
  2175.  
  2176. =item Asc
  2177.  
  2178. Sets the ASCII transfer mode for this FTP session.  It will be applied
  2179. to the subsequent C<Get> functions.  See also the C<Binary> and
  2180. C<Mode> function.
  2181.  
  2182. Example:
  2183.  
  2184.     $FTP->Ascii();
  2185.  
  2186. =item Binary
  2187.  
  2188. =item Bin
  2189.  
  2190. Sets the binary transfer mode for this FTP session.  It will be
  2191. applied to the subsequent C<Get> functions.  See also the C<Ascii> and
  2192. C<Mode> function.
  2193.  
  2194. Example:
  2195.  
  2196.     $FTP->Binary();
  2197.  
  2198. =item Cd path
  2199.  
  2200. =item Cwd path
  2201.  
  2202. =item Chdir path
  2203.  
  2204. Changes the current directory on the FTP remote host.  Returns I<path>
  2205. or C<undef> on error.
  2206.  
  2207. Example:
  2208.  
  2209.     $FTP->Cd("/pub");
  2210.  
  2211. =item Delete file
  2212.  
  2213. =item Del file
  2214.  
  2215. Deletes a file on the FTP remote host.  Returns C<undef> on error.
  2216.  
  2217. Example:
  2218.  
  2219.     $FTP->Delete("110-i86.zip");
  2220.  
  2221. =item Get remote, [local, overwrite, flags, context]
  2222.  
  2223. Gets the I<remote> FTP file and saves it locally in I<local>.  If
  2224. I<local> is not specified, it will be the same name as I<remote>.
  2225. Returns C<undef> on error.  The parameters and their values are:
  2226.  
  2227. =over
  2228.  
  2229. =item * remote
  2230.  
  2231. The name of the remote file on the FTP server.  Default: I<none>.
  2232.  
  2233. =item * local
  2234.  
  2235. The name of the local file to create.  Default: remote.
  2236.  
  2237. =item * overwrite
  2238.  
  2239. If 0, overwrites I<local> if it exists; with any other value, the
  2240. function fails if the I<local> file already exists.  Default: 0.
  2241.  
  2242. =item * flags
  2243.  
  2244. Additional flags affecting the behavior of the function.  Default:
  2245. I<none>.
  2246.  
  2247. =item * context
  2248.  
  2249. A number to identify this operation if it is asynchronous.  See
  2250. C<SetStatusCallback> and C<GetStatusCallback> for more info on
  2251. asynchronous operations.  Default: I<none>.
  2252.  
  2253. =back
  2254.  
  2255. Refer to the L<"Microsoft Win32 Internet Functions"> documentation for
  2256. more details on those parameters.
  2257.  
  2258. Example:
  2259.  
  2260.     $FTP->Get("110-i86.zip");
  2261.     $FTP->Get("/pub/perl/languages/CPAN/00index.html", "CPAN_index.html");
  2262.  
  2263. =item List [pattern, listmode]
  2264.  
  2265. =item Ls [pattern, listmode]
  2266.  
  2267. =item Dir [pattern, listmode]
  2268.  
  2269. Returns a list containing the files found in this directory,
  2270. eventually matching the given I<pattern> (which, if omitted, is
  2271. considered "*.*").  The content of the returned list depends on the
  2272. I<listmode> parameter, which can have the following values:
  2273.  
  2274. =over
  2275.  
  2276. =item * listmode=1 (or omitted)
  2277.  
  2278. the list contains the names of the files found.  Example:
  2279.  
  2280.     @files = $FTP->List();
  2281.     @textfiles = $FTP->List("*.txt");
  2282.     foreach $file (@textfiles) {
  2283.       print "Name: ", $file, "\n";
  2284.     }
  2285.  
  2286. =item * listmode=2
  2287.  
  2288. the list contains 7 values for each file, which respectively are:
  2289.  
  2290. =over
  2291.  
  2292. =item * the file name
  2293.  
  2294. =item * the DOS short file name, aka 8.3
  2295.  
  2296. =item * the size
  2297.  
  2298. =item * the attributes
  2299.  
  2300. =item * the creation time
  2301.  
  2302. =item * the last access time
  2303.  
  2304. =item * the last modified time
  2305.  
  2306. =back
  2307.  
  2308. Example:
  2309.  
  2310.     @files = $FTP->List("*.*", 2);
  2311.     for($i=0; $i<=$#files; $i+=7) {
  2312.       print "Name: ", @files[$i], "\n";
  2313.       print "Size: ", @files[$i+2], "\n";
  2314.       print "Attr: ", @files[$i+3], "\n";
  2315.     }
  2316.  
  2317. =item * listmode=3
  2318.  
  2319. the list contains a reference to an hash array for each found file;
  2320. each hash contains:
  2321.  
  2322. =over
  2323.  
  2324. =item * name => the file name
  2325.  
  2326. =item * altname => the DOS short file name, aka 8.3
  2327.  
  2328. =item * size => the size
  2329.  
  2330. =item * attr => the attributes
  2331.  
  2332. =item * ctime => the creation time
  2333.  
  2334. =item * atime => the last access time
  2335.  
  2336. =item * mtime => the last modified time
  2337.  
  2338. =back
  2339.  
  2340. Example:
  2341.  
  2342.     @files = $FTP->List("*.*", 3);
  2343.     foreach $file (@files) {
  2344.       print $file->{'name'}, " ", $file->{'size'}, " ", $file->{'attr'}, "\n";
  2345.     }
  2346.  
  2347. B<Note:> all times are reported as strings of the following format:
  2348. I<second, hour, minute, day, month, year>.
  2349.  
  2350. Example:
  2351.  
  2352.     $file->{'mtime'} == "0,10,58,9,12,1996" stands for 09 Dec 1996 at 10:58:00
  2353.  
  2354. =back
  2355.  
  2356. =item Mkdir name
  2357.  
  2358. =item Md name
  2359.  
  2360. Creates a directory on the FTP remote host.  Returns C<undef> on error.
  2361.  
  2362. Example:
  2363.  
  2364.     $FTP->Mkdir("NextBuild");
  2365.  
  2366. =item Mode [mode]
  2367.  
  2368. If called with no arguments, returns the current transfer mode for
  2369. this FTP session ("asc" for ASCII or "bin" for binary).  The I<mode>
  2370. argument can be "asc" or "bin", in which case the appropriate transfer
  2371. mode is selected.  See also the Ascii and Binary functions.  Returns
  2372. C<undef> on errors.
  2373.  
  2374. Example:
  2375.  
  2376.     print "Current mode is: ", $FTP->Mode();
  2377.     $FTP->Mode("asc"); # ...  same as $FTP->Ascii();
  2378.  
  2379. =item Pasv [mode]
  2380.  
  2381. If called with no arguments, returns 1 if the current FTP session has
  2382. passive transfer mode enabled, 0 if not.
  2383.  
  2384. You can call it with a I<mode> parameter (0/1) only as a method of a
  2385. Internet object (see C<new>), in which case it will set the default
  2386. value for the next C<FTP> objects you create (read: set it before,
  2387. because you can't change this value once you opened the FTP session).
  2388.  
  2389. Example:
  2390.  
  2391.     print "Pasv is: ", $FTP->Pasv();
  2392.  
  2393.     $INET->Pasv(1);
  2394.     $INET->FTP($FTP,"ftp.activeware.com", "anonymous", "dada\@divinf.it");
  2395.     $FTP->Pasv(0); # this will be ignored...
  2396.  
  2397. =item Put local, [remote, context]
  2398.  
  2399. Upload the I<local> file to the FTP server saving it under the name
  2400. I<remote>, which if if omitted is the same name as I<local>.  Returns
  2401. C<undef> on error.
  2402.  
  2403. I<context> is a number to identify this operation if it is asynchronous.
  2404. See C<SetStatusCallback> and C<GetStatusCallback> for more info on
  2405. asynchronous operations.
  2406.  
  2407. Example:
  2408.  
  2409.     $FTP->Put("internet.zip");
  2410.     $FTP->Put("d:/users/dada/temp.zip", "/temp/dada.zip");
  2411.  
  2412. =item Pwd
  2413.  
  2414. Returns the current directory on the FTP server or C<undef> on errors.
  2415.  
  2416. Example:
  2417.  
  2418.     $path = $FTP->Pwd();
  2419.  
  2420. =item Rename oldfile, newfile
  2421.  
  2422. =item Ren oldfile, newfile
  2423.  
  2424. Renames a file on the FTP remote host.  Returns C<undef> on error.
  2425.  
  2426. Example:
  2427.  
  2428.     $FTP->Rename("110-i86.zip", "68i-011.zip");
  2429.  
  2430. =item Rmdir name
  2431.  
  2432. =item Rd name
  2433.  
  2434. Removes a directory on the FTP remote host.  Returns C<undef> on error.
  2435.  
  2436. Example:
  2437.  
  2438.     $FTP->Rmdir("CurrentBuild");
  2439.  
  2440. =back
  2441.  
  2442. =head2 HTTP Functions
  2443.  
  2444. B<General Note>
  2445.  
  2446. All methods assume that you have the following lines:
  2447.  
  2448.     use Win32::Internet;
  2449.     $INET = new Win32::Internet();
  2450.     $INET->HTTP($HTTP, "hostname", "username", "password");
  2451.  
  2452. somewhere before the method calls; in other words, we assume that you
  2453. have an Internet object called $INET and an open HTTP session called
  2454. $HTTP.
  2455.  
  2456. See C<new> and C<HTTP> for more information.
  2457.  
  2458.  
  2459. B<Methods>
  2460.  
  2461. =over
  2462.  
  2463. =item AddHeader header, [flags]
  2464.  
  2465. Adds HTTP request headers to an HTTP request object created with
  2466. C<OpenRequest>.  For the possible values of I<flags> refer to the
  2467. L<"Microsoft Win32 Internet Functions"> document.
  2468.  
  2469. Example:
  2470.  
  2471.     $HTTP->OpenRequest($REQUEST,"/index.html");
  2472.     $REQUEST->AddHeader("If-Modified-Since:  Sunday, 17-Nov-96 11:40:03 GMT");
  2473.     $REQUEST->AddHeader("Accept: text/html\r\n", HTTP_ADDREQ_FLAG_REPLACE);
  2474.  
  2475. =item OpenRequest requestobject, [path, method, version, referer, accept, flags, context]
  2476.  
  2477. =item OpenRequest requestobject, hashref
  2478.  
  2479. Opens an HTTP request.  Returns C<undef> on errors or a number if the
  2480. connection was succesful.  You can then use one of the C<AddHeader>,
  2481. C<SendRequest>, C<QueryInfo>, C<QueryDataAvailable> and C<ReadFile>
  2482. methods on the newly created I<requestobject>.  The parameters and
  2483. their values are:
  2484.  
  2485. =over
  2486.  
  2487. =item * path
  2488.  
  2489. The object to request.  This is generally a file name, an executable
  2490. module, etc.  Default: /
  2491.  
  2492. =item * method
  2493.  
  2494. The method to use; can actually be GET, POST, HEAD or PUT.  Default:
  2495. GET
  2496.  
  2497. =item * version
  2498.  
  2499. The HTTP version.  Default: HTTP/1.0
  2500.  
  2501. =item * referer
  2502.  
  2503. The URL of the document from which the URL in the request was
  2504. obtained.  Default: I<none>
  2505.  
  2506. =item * accept
  2507.  
  2508. The content types accepted.  They must be separated by a "\0" (ASCII
  2509. zero).  Default: text/* image/gif image/jpeg
  2510.  
  2511. =item * flags
  2512.  
  2513. Additional flags affecting the behavior of the function.  Default:
  2514. I<none>
  2515.  
  2516. =item * context
  2517.  
  2518. A number to identify this operation if it is asynchronous.  See
  2519. C<SetStatusCallback> and C<GetStatusCallback> for more info on
  2520. asynchronous operations.  Default: I<none>
  2521.  
  2522. =back
  2523.  
  2524. Refer to the L<"Microsoft Win32 Internet Functions"> documentation for
  2525. more details on those parameters.  If you pass I<hashref> (a reference to
  2526. an hash array), the following values are taken from the array:
  2527.  
  2528.     %hash=(
  2529.       "path"        => "path",
  2530.       "method"      => "method",
  2531.       "version"     => "version",
  2532.       "referer"     => "referer",
  2533.       "accept"      => "accept",
  2534.       "flags"       => flags,
  2535.       "context"     => context,
  2536.     );
  2537.  
  2538. See also C<Request>.
  2539.  
  2540. Example:
  2541.  
  2542.     $HTTP->OpenRequest($REQUEST, "/index.html");
  2543.     $HTTP->OpenRequest($REQUEST, "/index.html", "GET", "HTTP/0.9");
  2544.  
  2545.     $params{"path"} = "/index.html";
  2546.     $params{"flags"} = "
  2547.     $HTTP->OpenRequest($REQUEST, \%params);
  2548.  
  2549. =item QueryInfo header, [flags]
  2550.  
  2551. Queries information about an HTTP request object created with
  2552. C<OpenRequest>.  You can specify an I<header> (for example,
  2553. "Content-type") and/or one or more I<flags>.  If you don't specify
  2554. I<flags>, HTTP_QUERY_CUSTOM will be used by default; this means that
  2555. I<header> should contain a valid HTTP header name.  For the possible
  2556. values of I<flags> refer to the L<"Microsoft Win32 Internet
  2557. Functions"> document.
  2558.  
  2559. Example:
  2560.  
  2561.     $HTTP->OpenRequest($REQUEST,"/index.html");
  2562.     $statuscode = $REQUEST->QueryInfo("", HTTP_QUERY_STATUS_CODE);
  2563.     $headers = $REQUEST->QueryInfo("", HTTP_QUERY_RAW_HEADERS_CRLF); # will get all the headers
  2564.     $length = $REQUEST->QueryInfo("Content-length");
  2565.  
  2566. =item Request [path, method, version, referer, accept, flags]
  2567.  
  2568. =item Request hashref
  2569.  
  2570. Performs an HTTP request and returns an array containing the status
  2571. code, the headers and the content of the file.  It is a one-step
  2572. procedure that makes an C<OpenRequest>, a C<SendRequest>, some
  2573. C<QueryInfo>, C<ReadFile> and finally C<Close>.  For a description of
  2574. the parameters, see C<OpenRequest>.
  2575.  
  2576. Example:
  2577.  
  2578.     ($statuscode, $headers, $file) = $HTTP->Request("/index.html");
  2579.     ($s, $h, $f) = $HTTP->Request("/index.html", "GET", "HTTP/1.0");
  2580.  
  2581. =item SendRequest [postdata]
  2582.  
  2583. Send an HTTP request to the destination server.  I<postdata> are any
  2584. optional data to send immediately after the request header; this is
  2585. generally used for POST or PUT requests.  See also C<OpenRequest>.
  2586.  
  2587. Example:
  2588.  
  2589.     $HTTP->OpenRequest($REQUEST, "/index.html");
  2590.     $REQUEST->SendRequest();
  2591.  
  2592.     # A POST request...
  2593.     $HTTP->OpenRequest($REQUEST, "/cgi-bin/somescript.pl", "POST");
  2594.  
  2595.     #This line is a must -> (thanks Philip :)
  2596.     $REQUEST->AddHeader("Content-Type: application/x-www-form-urlencoded");
  2597.  
  2598.     $REQUEST->SendRequest("key1=value1&key2=value2&key3=value3");
  2599.  
  2600. =back
  2601.  
  2602.  
  2603. =head1 APPENDIX
  2604.  
  2605.  
  2606. =head2 Microsoft Win32 Internet Functions
  2607.  
  2608. Complete documentation for the Microsoft Win32 Internet Functions can
  2609. be found, in both HTML and zipped Word format, at this address:
  2610.  
  2611.     http://www.microsoft.com/intdev/sdk/docs/wininet/
  2612.  
  2613. =head2 Functions Table
  2614.  
  2615. This table reports the correspondence between the functions offered by
  2616. WININET.DLL and their implementation in the Win32::Internet
  2617. extension. Functions showing a "---" are not currently
  2618. implemented. Functions enclosed in parens ( ) aren't implemented
  2619. straightforwardly, but in a higher-level routine, eg. together with
  2620. other functions.
  2621.  
  2622.     WININET.DLL                     Win32::Internet
  2623.  
  2624.     InternetOpen                    new Win32::Internet
  2625.     InternetConnect                 FTP / HTTP
  2626.     InternetCloseHandle             Close
  2627.     InternetQueryOption             QueryOption
  2628.     InternetSetOption               SetOption
  2629.     InternetSetOptionEx             ---
  2630.     InternetSetStatusCallback       SetStatusCallback
  2631.     InternetStatusCallback          GetStatusCallback
  2632.     InternetConfirmZoneCrossing     ---
  2633.     InternetTimeFromSystemTime      TimeConvert
  2634.     InternetTimeToSystemTime        TimeConvert
  2635.     InternetAttemptConnect          ---
  2636.     InternetReadFile                ReadFile
  2637.     InternetSetFilePointer          ---
  2638.     InternetFindNextFile            (List)
  2639.     InternetQueryDataAvailable      QueryDataAvailable
  2640.     InternetGetLastResponseInfo     GetResponse
  2641.     InternetWriteFile               ---
  2642.     InternetCrackUrl                CrackURL
  2643.     InternetCreateUrl               CreateURL
  2644.     InternetCanonicalizeUrl         CanonicalizeURL
  2645.     InternetCombineUrl              CombineURL
  2646.     InternetOpenUrl                 OpenURL
  2647.     FtpFindFirstFile                (List)
  2648.     FtpGetFile                      Get
  2649.     FtpPutFile                      Put
  2650.     FtpDeleteFile                   Delete
  2651.     FtpRenameFile                   Rename
  2652.     FtpOpenFile                     ---
  2653.     FtpCreateDirectory              Mkdir
  2654.     FtpRemoveDirectory              Rmdir
  2655.     FtpSetCurrentDirectory          Cd
  2656.     FtpGetCurrentDirectory          Pwd
  2657.     HttpOpenRequest                 OpenRequest
  2658.     HttpAddRequestHeaders           AddHeader
  2659.     HttpSendRequest                 SendRequest
  2660.     HttpQueryInfo                   QueryInfo
  2661.     InternetErrorDlg                ---
  2662.  
  2663.  
  2664. Actually, I don't plan to add support for Gopher, Cookie and Cache
  2665. functions. I will if there will be consistent requests to do so.
  2666.  
  2667. There are a number of higher-level functions in the Win32::Internet
  2668. that simplify some usual procedures, calling more that one WININET API
  2669. function. This table reports those functions and the relative WININET
  2670. functions they use.
  2671.  
  2672.     Win32::Internet                 WININET.DLL
  2673.  
  2674.     FetchURL                        InternetOpenUrl
  2675.                                     InternetQueryDataAvailable
  2676.                                     InternetReadFile
  2677.                                     InternetCloseHandle
  2678.  
  2679.     ReadEntireFile                  InternetQueryDataAvailable
  2680.                                     InternetReadFile
  2681.  
  2682.     Request                         HttpOpenRequest
  2683.                                     HttpSendRequest
  2684.                                     HttpQueryInfo
  2685.                                     InternetQueryDataAvailable
  2686.                                     InternetReadFile
  2687.                                     InternetCloseHandle
  2688.  
  2689.     List                            FtpFindFirstFile
  2690.                                     InternetFindNextFile
  2691.  
  2692.  
  2693. =head2 Constants
  2694.  
  2695. Those are the constants exported by the package in the main namespace
  2696. (eg. you can use them in your scripts); for their meaning and proper
  2697. use, refer to the Microsoft Win32 Internet Functions document.
  2698.  
  2699.     HTTP_ADDREQ_FLAG_ADD
  2700.     HTTP_ADDREQ_FLAG_REPLACE
  2701.     HTTP_QUERY_ALLOW
  2702.     HTTP_QUERY_CONTENT_DESCRIPTION
  2703.     HTTP_QUERY_CONTENT_ID
  2704.     HTTP_QUERY_CONTENT_LENGTH
  2705.     HTTP_QUERY_CONTENT_TRANSFER_ENCODING
  2706.     HTTP_QUERY_CONTENT_TYPE
  2707.     HTTP_QUERY_COST
  2708.     HTTP_QUERY_CUSTOM
  2709.     HTTP_QUERY_DATE
  2710.     HTTP_QUERY_DERIVED_FROM
  2711.     HTTP_QUERY_EXPIRES
  2712.     HTTP_QUERY_FLAG_REQUEST_HEADERS
  2713.     HTTP_QUERY_FLAG_SYSTEMTIME
  2714.     HTTP_QUERY_LANGUAGE
  2715.     HTTP_QUERY_LAST_MODIFIED
  2716.     HTTP_QUERY_MESSAGE_ID
  2717.     HTTP_QUERY_MIME_VERSION
  2718.     HTTP_QUERY_PRAGMA
  2719.     HTTP_QUERY_PUBLIC
  2720.     HTTP_QUERY_RAW_HEADERS
  2721.     HTTP_QUERY_RAW_HEADERS_CRLF
  2722.     HTTP_QUERY_REQUEST_METHOD
  2723.     HTTP_QUERY_SERVER
  2724.     HTTP_QUERY_STATUS_CODE
  2725.     HTTP_QUERY_STATUS_TEXT
  2726.     HTTP_QUERY_URI
  2727.     HTTP_QUERY_USER_AGENT
  2728.     HTTP_QUERY_VERSION
  2729.     HTTP_QUERY_WWW_LINK
  2730.     ICU_BROWSER_MODE
  2731.     ICU_DECODE
  2732.     ICU_ENCODE_SPACES_ONLY
  2733.     ICU_ESCAPE
  2734.     ICU_NO_ENCODE
  2735.     ICU_NO_META
  2736.     ICU_USERNAME
  2737.     INTERNET_FLAG_PASSIVE
  2738.     INTERNET_FLAG_ASYNC
  2739.     INTERNET_FLAG_HYPERLINK
  2740.     INTERNET_FLAG_KEEP_CONNECTION
  2741.     INTERNET_FLAG_MAKE_PERSISTENT
  2742.     INTERNET_FLAG_NO_AUTH
  2743.     INTERNET_FLAG_NO_AUTO_REDIRECT
  2744.     INTERNET_FLAG_NO_CACHE_WRITE
  2745.     INTERNET_FLAG_NO_COOKIES
  2746.     INTERNET_FLAG_READ_PREFETCH
  2747.     INTERNET_FLAG_RELOAD
  2748.     INTERNET_FLAG_RESYNCHRONIZE
  2749.     INTERNET_FLAG_TRANSFER_ASCII
  2750.     INTERNET_FLAG_TRANSFER_BINARY
  2751.     INTERNET_INVALID_PORT_NUMBER
  2752.     INTERNET_INVALID_STATUS_CALLBACK
  2753.     INTERNET_OPEN_TYPE_DIRECT
  2754.     INTERNET_OPEN_TYPE_PROXY
  2755.     INTERNET_OPEN_TYPE_PROXY_PRECONFIG
  2756.     INTERNET_OPTION_CONNECT_BACKOFF
  2757.     INTERNET_OPTION_CONNECT_RETRIES
  2758.     INTERNET_OPTION_CONNECT_TIMEOUT
  2759.     INTERNET_OPTION_CONTROL_SEND_TIMEOUT
  2760.     INTERNET_OPTION_CONTROL_RECEIVE_TIMEOUT
  2761.     INTERNET_OPTION_DATA_SEND_TIMEOUT
  2762.     INTERNET_OPTION_DATA_RECEIVE_TIMEOUT
  2763.     INTERNET_OPTION_HANDLE_TYPE
  2764.     INTERNET_OPTION_LISTEN_TIMEOUT
  2765.     INTERNET_OPTION_PASSWORD
  2766.     INTERNET_OPTION_READ_BUFFER_SIZE
  2767.     INTERNET_OPTION_USER_AGENT
  2768.     INTERNET_OPTION_USERNAME
  2769.     INTERNET_OPTION_VERSION
  2770.     INTERNET_OPTION_WRITE_BUFFER_SIZE
  2771.     INTERNET_SERVICE_FTP
  2772.     INTERNET_SERVICE_GOPHER
  2773.     INTERNET_SERVICE_HTTP
  2774.     INTERNET_STATUS_CLOSING_CONNECTION
  2775.     INTERNET_STATUS_CONNECTED_TO_SERVER
  2776.     INTERNET_STATUS_CONNECTING_TO_SERVER
  2777.     INTERNET_STATUS_CONNECTION_CLOSED
  2778.     INTERNET_STATUS_HANDLE_CLOSING
  2779.     INTERNET_STATUS_HANDLE_CREATED
  2780.     INTERNET_STATUS_NAME_RESOLVED
  2781.     INTERNET_STATUS_RECEIVING_RESPONSE
  2782.     INTERNET_STATUS_REDIRECT
  2783.     INTERNET_STATUS_REQUEST_COMPLETE
  2784.     INTERNET_STATUS_REQUEST_SENT
  2785.     INTERNET_STATUS_RESOLVING_NAME
  2786.     INTERNET_STATUS_RESPONSE_RECEIVED
  2787.     INTERNET_STATUS_SENDING_REQUEST
  2788.  
  2789.  
  2790. =head1 VERSION HISTORY
  2791.  
  2792. =over
  2793.  
  2794. =item * 0.082 (4 Sep 2001)
  2795.  
  2796. =over
  2797.  
  2798. =item *
  2799.  
  2800. Fix passive FTP mode.  INTERNET_FLAG_PASSIVE was misspelled in earlier
  2801. versions (as INTERNET_CONNECT_FLAG_PASSIVE) and wouldn't work.  Found
  2802. by Steve Raynesford <stever@evolvecomm.com>.
  2803.  
  2804. =back
  2805.  
  2806. =item * 0.081 (25 Sep 1999)
  2807.  
  2808. =over
  2809.  
  2810. =item *
  2811.  
  2812. Documentation converted to pod format by Jan Dubois <JanD@ActiveState.com>.
  2813.  
  2814. =item *
  2815.  
  2816. Minor changes from Perl 5.005xx compatibility.
  2817.  
  2818. =back
  2819.  
  2820. =item * 0.08 (14 Feb 1997)
  2821.  
  2822. =over
  2823.  
  2824. =item *
  2825.  
  2826. fixed 2 more bugs in Option(s) related subs (thanks to Brian
  2827. Helterline!).
  2828.  
  2829. =item *
  2830.  
  2831. Error() now gets error messages directly from WININET.DLL.
  2832.  
  2833. =item *
  2834.  
  2835. The PLL file now comes in 2 versions, one for Perl version 5.001
  2836. (build 100) and one for Perl version 5.003 (build 300 and
  2837. higher). Everybody should be happy now :)
  2838.  
  2839. =item *
  2840.  
  2841. added an installation program.
  2842.  
  2843. =back
  2844.  
  2845. =item * 0.07 (10 Feb 1997)
  2846.  
  2847. =over
  2848.  
  2849. =item *
  2850.  
  2851. fixed a bug in Version() introduced with 0.06...
  2852.  
  2853. =item *
  2854.  
  2855. completely reworked PM file, fixed *lots* of minor bugs, and removed
  2856. almost all the warnings with "perl -w".
  2857.  
  2858. =back
  2859.  
  2860. =item * 0.06 (26 Jan 1997)
  2861.  
  2862. =over
  2863.  
  2864. =item *
  2865.  
  2866. fixed another hideous bug in "new" (the 'class' parameter was still
  2867. missing).
  2868.  
  2869. =item *
  2870.  
  2871. added support for asynchronous operations (work still in embryo).
  2872.  
  2873. =item *
  2874.  
  2875. removed the ending \0 (ASCII zero) from the DLL version returned by
  2876. "Version".
  2877.  
  2878. =item *
  2879.  
  2880. added a lot of constants.
  2881.  
  2882. =item *
  2883.  
  2884. added safefree() after every safemalloc() in C... wonder why I didn't
  2885. it before :)
  2886.  
  2887. =item *
  2888.  
  2889. added TimeConvert, which actually works one way only.
  2890.  
  2891. =back
  2892.  
  2893. =item * 0.05f (29 Nov 1996)
  2894.  
  2895. =over
  2896.  
  2897. =item *
  2898.  
  2899. fixed a bug in "new" (parameters passed were simply ignored).
  2900.  
  2901. =item *
  2902.  
  2903. fixed another bug: "Chdir" and "Cwd" were aliases of RMDIR instead of
  2904. CD..
  2905.  
  2906. =back
  2907.  
  2908. =item * 0.05 (29 Nov 1996)
  2909.  
  2910. =over
  2911.  
  2912. =item *
  2913.  
  2914. added "CrackURL" and "CreateURL".
  2915.  
  2916. =item *
  2917.  
  2918. corrected an error in TEST.PL (there was a GetUserAgent instead of
  2919. UserAgent).
  2920.  
  2921. =back
  2922.  
  2923. =item * 0.04 (25 Nov 1996)
  2924.  
  2925. =over
  2926.  
  2927. =item *
  2928.  
  2929. added "Version" to retrieve package and DLL versions.
  2930.  
  2931. =item *
  2932.  
  2933. added proxies and other options to "new".
  2934.  
  2935. =item *
  2936.  
  2937. changed "OpenRequest" and "Request" to read parameters from a hash.
  2938.  
  2939. =item *
  2940.  
  2941. added "SetOption/QueryOption" and a lot of relative functions
  2942. (connect, username, password, useragent, etc.).
  2943.  
  2944. =item *
  2945.  
  2946. added "CanonicalizeURL" and "CombineURL".
  2947.  
  2948. =item *
  2949.  
  2950. "Error" covers a wider spectrum of errors.
  2951.  
  2952. =back
  2953.  
  2954. =item * 0.02 (18 Nov 1996)
  2955.  
  2956. =over
  2957.  
  2958. =item *
  2959.  
  2960. added support for HTTP sessions and requests.
  2961.  
  2962. =back
  2963.  
  2964. =item * 0.01 (11 Nov 1996)
  2965.  
  2966. =over
  2967.  
  2968. =item *
  2969.  
  2970. fetching of HTTP, FTP and GOPHER URLs.
  2971.  
  2972. =item *
  2973.  
  2974. complete set of commands to manage an FTP session.
  2975.  
  2976. =back
  2977.  
  2978. =back
  2979.  
  2980. =head1 AUTHOR
  2981.  
  2982. Version 0.08 (14 Feb 1997) by Aldo Calpini <a.calpini@romagiubileo.it>
  2983.  
  2984.  
  2985. =head1 CREDITS
  2986.  
  2987. Win32::Internet is based on the Win32::Registry code written by Jesse
  2988. Dougherty.
  2989.  
  2990. Additional thanks to: Carl Tichler for his help in the initial
  2991. development; Tore Haraldsen, Brian Helterline for the bugfixes; Dave
  2992. Roth for his great source code examples.
  2993.  
  2994.  
  2995. =head1 DISCLAIMER
  2996.  
  2997. This program is FREE; you can redistribute, modify, disassemble, or
  2998. even reverse engineer this software at your will. Keep in mind,
  2999. however, that NOTHING IS GUARANTEED to work and everything you do is
  3000. AT YOUR OWN RISK - I will not take responsability for any damage, loss
  3001. of money and/or health that may arise from the use of this program!
  3002.  
  3003. This is distributed under the terms of Larry Wall's Artistic License.
  3004.